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About This Manual 





This manual describes advanced procedures and provides technical 
information of use to the advanced user. 


Some of the information in this manual may not apply to you. For 
example, the chapter on Gateway engine configuration does not 
apply to Server or Workstation engines. Such information is clearly 
marked throughout the manual. 


Pervasive Software would appreciate your comments and 
suggestions about this manual. As a user of our documentation, you 
are in a unique position to provide ideas that can have a direct impact 
on future releases of this and other manuals. If you have comments 
or suggestions for the product documentation, post your request at 
http://webforum.pervasive.com/devtalk/ or send E-mail to 
docs@pervasive.com. 
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Who Should Read This Manual 


This manual is provided for advanced users. Advanced users are 
considered to have a strong understanding of the underlying 
operating systems on which you run your Pervasive.SQL-based 
applications. Advanced users should be comfortable configuring 
their operating system, and in many cases, must have administrative 
permissions to configure the database engine. Advanced users may 
include the following; 


= network administrators of networks where one or more 
Pervasive.SQL-based applications are installed 
m value-added resellers of Pervasive.SQL-based applications 


m developers of Pervasive.SQL-based applications 
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Manual Organization 


The following list briefly describes each chapter in the manual: 


Chapter 1—“Concepts of Database Maintenance” 


This chapter provides a brief introduction to the basic concepts 
and procedures involved with the job of maintaining a database. 


Chapter 2—“Understanding the Pervasive Component 
Architecture” 


This chapter explains in some detail the major components that 
make up Pervasive.SQL and some of their unique features. 


Chapter 3—“Changing Your Configuration” 


This chapter explains how to use the graphical utility named 
Configuration and how to tune database engine performance. 


Chapter 4—“Configuration Reference” 


This chapter provides detailed information about all of the 
available configuration options for engines, 32-bit clients, and 
16-bit clients. 


Chapter 5—“Identifiers, DSNs, and Named Databases” 


This chapter explains internal database names, public Data 
Source Names, and the limits on identifiers, such as table names, 
within a database. 


Chapter 6—“Setting Up Referential Integrity” 


This chapter explains how to setup referential integrity rules to 
enforce the internal consistency of related data. 


Chapter 7—“Owner Names and Relational Security” 


This chapter explains Btrieve security and SQL security and how 
the two schemes interact. 


Chapter 8—“Backup and Restore” 


This chapter describes how to develop a regular backup 
procedure to ensure your data is protected, and how to restore 
from backup if necessary. 
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= Chapter 9—“Workgroup Engine in Depth” 


This chapter provides technical details and advanced procedures 
regarding the Workgroup engine. 


m Chapter 10—“Monitoring Database Resources” 


This chapter explains how to use the graphical utility named 
Monitor to view users connected to a database, file usage 
information, and resource usage information. 


= Chapter 11—“Testing Btrieve Operations Using the Function 
Executor” 


This chapter explains how to use the utility named Function 
Executor to perform individual Btrieve operations. 


m Chapter 12—“Adding Relational Access to Btrieve Files” 


This chapter explains how to create DDFs for existing Btrieve 
files so that they can be accessed via ODBC. 


m Chapter 13—“Manipulating Btrieve Data Files with 
Maintenance” 


This chapter covers the graphical utility named Maintenance 
and the variety of functions it provides. 


m Chapter 14—“Converting Pervasive.SQL 2000i Data” 


This chapter covers the graphical utility named Rebuild and its 
functions, such as upgrading the file format version of a Btrieve 
file. 


=» Appendix A—“Description Files” 


This appendix covers how to use description files to archive 
information about Btrieve data files you have created. 


This manual also includes an index. 
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Conventions 


Unless otherwise noted, command syntax, code, and examples use 
the following conventions: 


CASE Commands and reserved words typically appear in uppercase 
letters. Unless the manual states otherwise, you can enter 
these items using uppercase, lowercase, or both. For 
example, you can type MYPROG, myprog, or MYprog. 


Bold Words appearing in bold include the following: menu names, 
dialog box names, commands, options, buttons, statements, 
etc. 

Monospaced Monospaced font is reserved for words you enter, such as 

font command syntax. 

[ ] Square brackets enclose optional information, as in [log_name]. 


If information is not enclosed in square brackets, it is required. 


A vertical bar indicates a choice of information to enter, as in 
[file name | O file name]. 


<> Angle brackets enclose multiple choices for a required item, as 
in /D=<5|6|7>. 


variable Words appearing in italics are variables that you must replace 
with appropriate values, as in file name. 


An ellipsis following information indicates you can repeat the 
information more than one time, as in [parameter ...]. 


= The symbol ::= means one item is defined in terms of another. 
For example, a::=b means the item a is defined in terms of b. 
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An Introduction to Database Maintenance 


Pervasive.SQL 2000i is a comprehensive database management 
system built around Pervasive Software’s MicroKernel Database 
Engine. Pervasive.SQL offers easy installation, uncomplicated 
maintenance, and high levels of performance and reliability. While 
Pervasive.SQL can run for months or years with practically no 
maintenance, you can get the most out of it by understanding some 
of its unique features and learning how to perform useful tasks. This 
manual describes how to tune, configure, and manage your 
Pervasive.SQL engine and associated databases. 

m “File Structure” on page 1-2 

m “Access Methods” on page 1-4 

m “Client/Server Communications” on page 1-5 

m “Configurations” on page 1-6 

= “Database Security” on page 1-8 

m “Data Archival and Restoration” on page 1-9 

m “Troubleshooting” on page 1-10 


= “Summary of Pervasive.SQL Utilities” on page 1-11 
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File Structure 


All Pervasive.SQL databases use a common data format. This 
commonality allows different access methods, such as transactional 
and relational, to the same data. The database management system 
through which all access methods operate is called the MicroKernel 
Database Engine (MKDE). 


Each Pervasive.SQL database table is a separate file with a default file 
extension of MKD. A MicroKernel file may contain both data and 
indexes, and is organized into various types of pages. A MicroKernel 
files contains data in the common data format. 


Each Pervasive.SQL database also contains a set of data dictionary 
files, with a file extension of DDF. The DDF files contain the schema 
of the database. Each database has, at a minimum, three DDF files: 
file.ddf, field.daf, and index.ddf. 


(The MKDE is completely unconcerned with the schema of the data 
apart from the key fields. However, the provision for referential 
integrity or access via SQL requires knowledge of the schema.) 


The names and locations of Pervasive.SOL databases are contained 
in a binary file named dbnames . cfg. On Windows-based systems, 
this file is located in the :winsysdir? directory. The file is located at 
sys:system\ for Netware. On Linux systems, the file is located at 
/usr/local/psql/etc/, and on Solaris at /opt/PVSWpsql/etc/. 
These locations represent the installation defaults. 


File Structure 


All of the files associated with a Pervasive.SOL database can be 
viewed from the operating system. Table 1-1 summarizes the 


associated files. 


Table 1-1 Files Associated With a Pervasive.SQL Database 





Type 


Description 





Database Names 
Configuration 


The dbnames . cfg file. Contains the names and locations 
of the Pervasive.SQL databases. 





Table Data 
(common data 
format) 


Files named, by default, tablename . MKD. Each database 
table has a corresponding MicroKernel file. 





Data Dictionary 








Files with an extension of DDF. At a minimum, three always 
exist for each database: File.DDF, Field.DDF and 
Index.DDF. 
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Access Methods 


The two primary methods in which data is accessed from 
Pervasive.SQL databases are transactional and relational. 


With transactional, an application program navigates up and down 
along either physical or logical pathways through data records. Using 
a navigational API, an application program provides direct control 
and allows a developer to optimize data access based on knowledge 
of the underlying structure of the data. Btrieve is an example of a 
navigational database engine. 


Relational is an access method in which data is represented as 
collections of tables, rows, and columns. The relational model 
insulates the developer from the underlying data structure and 
presents the data in a simple table format. ODBC is an example of a 
relational access method. 


A single application program may include both types of access. For 
example, an application may use transactional access for adding and 
changing data, and relational access for querying the data and report 
writing. 


You need to know the access method(s) used by the application 
programs that rely on your installation of Pervasive.SQL. The access 
methods may have different configurations. You may need to 
customize the configuration to optimize a particular access method. 


Also, troubleshooting is easier when you are aware of the access 
method(s) used by a given application program. For example, if an 
application program uses relational access through ODBC, you may 
need to troubleshoot a problem at the ODBC level rather than at the 
database management system. 


See Chapters 3 and 4 for the tasks and references pertaining to 
customizing configurations. 
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Client/Server Communications 


The MKDE supports two types of processing modes, stand-alone 
(also called workstation) and client/server. A stand-alone 
application program accesses a local copy of the MKDE. The local 
MKDE calls upon the operating system of the workstation which 
performs the I/O on a local or networked hard disk. 


Client/server mode uses a client/server MKDE executing ona shared 
file server. When an application program is operating in client/server 
mode, a communication program called a requester is called upon 
instead of the local MKDE. This requester passes transactional-level 
requests and data records between the application program and the 
client/server MKDE using the network protocol supported by the 
operating system. File I/O functions are completely bypassed in 
client/server mode and the workstation has no operating system 
handles allocated to shared data files. Database manipulation is 
performed by the server-based MKDE on behalf of each workstation. 


Note that the processing mode is determined by the configuration of 
the workstation and not the application program itself. This means 
that an application is capable of running in both workstation and 
client/server modes. The application program does not have to be 
recompiled to switch the application to client/server mode from 
workstation mode. 


The stand-alone version of Pervasive.SQL is referred to as the 
Workstation version. The client/server versions of the product 
include Workgroup and Server. 


The client/server configurations may be customized for the 
Workgroup and Server versions of Pervasive.SQL. A Configuration 
utility exists in the Pervasive Control Center (PCC) to facilitate the 
configuration of client/server configurations as well as stand-alone 
configurations. 


See Chapters 3 and 4 for the tasks pertaining to configuring the 
client/server communications and database engine. 
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Configurations 
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You can configure separate settings for the server and client aspects 
of the database engine. The settings allow you to optimize the 
performance of the engine based on your business requirements. 


Figure illustrates the flow from an application program to the 
database files at the operating system. The database engine resides 
between the application program and the data files. 


Figure 1-1 Conceptual View of Database Engine Configuration 


Pervasive.SQL Database Engine Configuration 
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The types of settings that you can configure for server include the 


following: 

m Access 

= Communications buffer size 

= Communication protocols 

= Compatibility (with previous versions of the MKDE) 
= Data integrity 

=» Debugging 

m Directories 

= Memory usage 

a Performance 





Configurations 


The types of settings that you can configure for client include the 
following: 


Access 

Communication protocols 
Performance 

Security 


Application characteristics 


You configure these settings within the PCC. See Chapters 3 and 4 for 
the tasks and references pertaining to configuration. 
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Database Security 
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The access to a Pervasive.SQL database can be protected several ways. 
Administrative-level security is set through the operating system. 
You can control who can administer a Pervasive.SQL database with 
the security mechanisms native to the operating system. 


Pervasive.SQL also provides security at the user and group levels. 
You can control who can access the data and at what capability. For 
example, for each table within a Pervasive.SQL database, you can 
specify whether a user or group can create, select, update, insert into, 
delete, or alter the table. 


You establish security by setting a password for the entire database. 
At that point, the only user authorized to access the database is a 
default user named Master. You can then add additional users and 
groups. 


Security can be set within the PCC. Also supported are two 
Structured Query Language (SQL) statements pertaining to security: 
GRANT and REVOKE. GRANT and REVOKE also allow you to set 
security at the column level if you choose. 


(The GRANT syntax integrates with Btrieve owner names, which 
provide security for use with the Btrieve interface. Btrieve owner 
names are essentially passwords that can be assigned to MicroKernel 
files along with certain types of behavior, such as read-only, read- 
write, and so forth.) 


See Chapter 7 for the tasks pertaining to security, users, and groups. 
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Data Archival and Restoration 


Backing up data is a routine part of protecting your databases and 
ensuring disaster recovery. You have several ways in which you can 
back up and restore your Pervasive.SQL databases. 


If your business allows you to stop all applications that access a 
Pervasive.SQL database, you may use any of the operating system 
utilities, or third-party software, to backup or restore the database 
files. 


Archival logging is another backup method that you can use to 
supplement operating system utilities. Archival logging allows you to 
keep a log of all database operations since your last backup. In case 
of a system failure, you can restore the data files from backup then 
roll forward the changes from the log file to return the system to the 
state it was in prior to the system failure. 


Continuous operations allows you to backup database files while the 
database engine is running and users are connected. After starting 
Continuous Operations, the database engine closes the active data 
files and stores all changes in temporary data files (called delta files). 
When the backup is complete, you turn off Continuous Operations. 
The database engine then reads the delta file and applies all the 
changes to the original data files. 


(The Pervasive System Analyzer, which runs on Win-32 platforms, 
lets you archive existing Pervasive.SQL components when you install 
a newer version of Pervasive.SQL. Although not used for backing up 
database files, the Pervasive System Analyzer is useful if you need to 
restore a previous version of the Pervasive.SQL product.) 


See Chapters 8 for the tasks pertaining to backing up and restoring 
databases. 
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Troubleshooting 


The Pervasive.SQL User's Guide and both of the Getting Started with 
Pervasive.SQL guides (Server and Workstation) contain 
troubleshooting information. A good place to start if you have 


troubleshooting questions is the troubleshooting chapter in those 
books. 


The Getting Started books contain troubleshooting information 
pertaining to installing the Pervasive.SQL products. The User's Guide 
contains general troubleshooting information as well as an extensive 
list of frequently asked questions (FAQs). 


The Pervasive System Analyzer is a utility that you may also use for 
troubleshooting. This utility lets you analyze system and archived 
components, test network communications, and test the database 
engines. 


Other resources at your disposal for troubleshooting include the 
Pervasive knowledge base, http://support.pervasive.com/kb, which 
contains information based on actual customer solutions and 
common problems, and Pervasive customer support at http:// 
www.pervasive.com/support. 


Note that your purchase of Pervasive products entitles you to 30 days 
of free technical support for installation and configuration 
problems. 


Summary of Pervasive.SQL Utilities 





Summary of Pervasive.SQL Utilities 


Pervasive.SQL comes with a variety of utilities designed to help you 
control and manage your databases. Most of the utilities run only on 
32-bit Windows and allow remote function to NetWare or Unix 

database server engines. 


Table 1-2 Summary of Pervasive.SQL Utilities 





























Utility name Runs on Description Server, 
these Workstation, or 
platforms Workgroup 
Pervasive Win32 Utilities warehouse for All 
Control Center Pervasive.SQL 2000i. Shows 
list of engines and databases 
available. 
Configuration Win32 Manipulates settings for All 
Pervasive client and server 
components. 
Monitor Win32 Monitors server engine Server, 
activity, useful for database Workgroup, 
administration and Workstation - local 
programming diagnostics. 
Server - remote 
Function Win16, Executes Btrieve operations, | All 
Executor Win32 enabling you to learn how the 
Btrieve interface works or test 
and debug an application. 
Pervasive.SQL | Win32and | Performs common Windows NT and 
Maintenance NetWare Pervasive.SQL file and data | NetWare servers 
manipulations, such as 
importing and exporting data. | All 32-bit Windows 
workstations and 
Unix for command- 
line version 
SQL Data Win32 Allows you to execute SQL All - local 
Manager - Statements interactively. 
invoked Creates and maintains Data | Server - remote 
automatically Dictionary Files (DDFs) and 
within PCC database files. 











1-11 


Concepts of Database Maintenance 


1-12 


Table 1-2 Summary of Pervasive.SQL Utilities 




















Utility name Runs on Description Server, 
these Workstation, or 
platforms Workgroup 
Rebuild Win16, Converts previous versions Windows and 
Win32, of MicroKernel files into more | NetWare servers 
and recent versions. 
NetWare Windows 32-bit 
workstations 
Command-line 
version on Unix 
User Count Win16and | Manages Pervasive.SQL Windows and 
Administrator Win32 user count keys andlicenses. | NetWare servers 
remotely 
Workgroup local 
Command-line 
version on Unix 
ODBC Win32 Sets up Data Source Names | All Windows 
Administrator (DSNs) for client and engine | engines - local 
interfaces 
Server - remote 
Gateway Win32 Used to configure and Workgroup engine 
Locator maintain gateway only 
configuration files for the 
workgroup engine. 
Pervasive Win32 Analyzes system All 
System components, runs 
Analyzer communication tests, and 








archives or restores 
database engine files on your 
system. 
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A Detailed Discussion of Smart Components and Related Features 


This chapter covers Smart Components and other features designed 
to offer a trouble-free environment for installing and running critical 
applications. This chapter is divided into the following sections: 

m “Pervasive.SQL 2000i Database Engine” on page 2-2 

m “Relational Architectural Overview” on page 2-7 

= “Overview of Smart Components” on page 2-11 

= “Component Identification” on page 2-13 

=» “Unique Component Naming” on page 2-14 

= “Dynamic Binding” on page 2-16 

m “Pervasive.SQL Event Logging” on page 2-18 

m “Error Code Clarification” on page 2-20 

= “Diagnosing Load Errors” on page 2-21 


m “Pervasive Auto-Reconnect” on page 2-23 
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Pervasive.SQL 2000i Database Engine 


Common Ad- 
dress Space 


Client/Server 
Version Check- 


ing 


Row Level 
Locking 
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The Pervasive.SQL 20001 engine consists of two database sub- 
engines: 


m MicroKernel Database Engine (MKDE), which provides Btrieve/ 
MicroKernel API support for Pervasive.SQL 2000i applications. 


= SQL Relational Database Engine (SRDE), which provides ODBC 
support for Pervasive.SQL 20001 applications. 


Pervasive.SQL uses an optimized memory architecture that provides 
high performance for both transactional and relational data access 
methods. Both the MKDE and the SRDE load and operate in the 
same process address space, minimizing the CPU time required to 
communicate between them. 


The client and server components include a feature designed to 
guarantee engine-to-client version compatibility. When a client 
requester first connects to an engine, the client requester compares 
its internal router version with the value returned from the engine by 
a Btrieve Version (26) call. If the client version is older than the 
engine, a message dialog box is displayed on the client system with 
the message “Engine components’ Version is different from Clients” 
along with a suggestion to run Pervasive System Analyzer (PSA). The 
same message is also logged in the client’s PVSW.LOG file. This 
message is only a warning. Although the client is not prevented from 
connecting to the engine in this situation, keep in mind that older 
clients are not tested against newer engines. Pervasive only 
guarantees compatibility between engines and clients if the clients 
are the same version as, or newer than, the engines. When prompted 
by this message, if you choose not to run PSA to archive older 
components and replace them with newer ones, you can expect the 
product to behave unpredictably until the client version is equal to 
or greater than the engine version. 


Row level locking improves database engine performance in multi- 
user environments in which many updates and writes occur at the 
same time, or in which transactions remain open for an extended 
period of time. 


MicroKernel 
Database En- 
gine 
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In releases prior to Pervasive.SQL 20001 SP3, the database engine 
locked data pages containing more than one record in order to 
update any record on that page. Any other client attempting to 
update records on that page while the page was still locked had to 
wait until the first operation released the page lock. This behavior 
occurred even though the records needed by the second operation 
were not affected by the first operation. 


With the current row level locking architecture, a transaction locks 
only the rows that it affects directly, not the entire page. One client 
can update records on a given page at the same time as another client 
updates different records on the same page. Waiting is necessary only 
when a second application attempts to modify the exact same 
records currently locked by the first application. Thus, row level 
locking decreases overall wait time and improves performance in a 
multi-user environment. 


This feature is completely transparent within the MicroKernel 
Database Engine. There are no changes to the Btrieve API, data file 
format, configuration settings, or any external component. This 
feature is always on and is supported across Server, Workgroup, and 
Workstation as well as all supported operating system platforms. 
This feature is supported for data file format v6.x and later. It is not 
supported for data file format v5.x or earlier. 


In this release, row level locking is implemented for key pages and 
data pages only, not variable pages. Furthermore, a small percentage 
of key page changes may cause key entries to move from one page to 
another. An example is when a key page is split or combined. These 
changes retain a full page lock until the transaction is completed. 


The MicroKernel Database Engine (MKDE) provides Btrieve/ 
MicroKernel API support for Pervasive.SQL 2000i applications. All 
versions of the engine—Server, Workstation, and Workgroup— 
support local applications running on the same computer as the 
engine. The server MKDE (which runs on Linux, Solaris, Windows 
NT, and NetWare) supports both local applications and remote 
(client/server) applications. The workgroup MKDE supports 
applications running on remote machines as well and will service 
requests made by another peer workgroup engine on a remote 
machine. 


There are four versions of the MicroKernel engine in this release. The 
server engine runs on Windows NT and NetWare. (The NetWare 
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version runs as an NLM directly on a NetWare server.) The 
workstation engine is a stand-alone engine that runs in Windows 95/ 
98/NT and cannot be accessed from remote machines. The fourth 
engine is the new workgroup engine. This engine can service 
requests from other workgroup engines or from the Pervasive.SQL 
requesters running on a remote machine. 


For servers, Btrieve client platforms include DOS and Windows 3.x/ 
95/98/NT. Win16 Btrieve applications running on a Win32 
workstation that is executing a Pervasive.SQL 2000i engine locally 
are supported using the existing Btrieve thunk mechanism. 
Thunking is also the default configuration for remote Pervasive.SQL 
20001 engine access from a Win16 Btrieve application running on a 
Win32 workstation. It is possible to build Btrieve applications as 
NLMs (NetWare Loadable Modules) that access a local MKDE on 
NetWare. DOS applications running on a Win95/98 machine use 
BTRBox95. 


The workstation MKDE is loaded when a Pervasive.SQL 20001 
application starts running and a Btrieve or ODBC API call is made. 
The workstation MKDE remains loaded in memory until all Btrieve 
or ODBC applications have correctly released engine resources, that 
is, they have logged out, closed files, and issued the correct number 
and type of Stop operations. 


The workgroup engine is by default configured to start up when you 
log into Windows. A workgroup engine can service requests made by 
another peer engine if the files have already been opened by the 
engine. It can also serve in a gateway mode by configuring a 
particular machine and database engine to act as a gateway, thus 
preventing another workgroup engine from opening the files. 


A “tray icon” is displayed to provide a graphical indication when a 
Pervasive.SQL 2000i workstation or workgroup MKDE is running. 
No tray icon is displayed when the workstation MKDE is not 
running. The tray icon does not display for the server engine. 


The Btrieve and ODBC APIs in Pervasive.SQL 2000i support writing 
distributed database applications that hide the details of connecting 
to a local or remote database engine from an application. Using this 
architecture, an application can access data that is co-located with 
the application (that is, running on the same computer as the 
application) while also accessing data on a remote computer. 
Moreover, a SQL database can be distributed by having DDFs (data 
dictionary files) serviced by a local MicroKernel Database Engine 


SQL Relational 
Database En- 
gine 
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and data files (tables) serviced by a remote MicroKernel Database 
Engine. Such a SQL database, which is not serviced exclusively by a 
local MicroKernel Database Engine, is referred to as a “mixed access 
database.” 


Mixed-access databases are subject to the following constraints: 


= The following features are not supported: referential integrity 
(RI), bound databases, triggers, distributed transaction 
atomicity (requires two-phase commit). 


m The SRDE and the MicroKernel Database Engine must be 
running on the same computer to access DDFs. 


= Data files for tables that are involved in an RI relationship, or 
those that have any triggers defined for them, or are in a bound 
named database, cannot be opened by a remote MicroKernel 
Database Engine. 


= When opening a file, the SRDE does not verify the version of the 
MicroKernel Database Engine servicing the request. If an 
operation that requires v6.30 or higher MicroKernel Database 
Engine API support (for example, shared locking) is issued to a 
MicroKernel Database Engine less than v6.30, then an error code 
is returned. When opening DDFs or when attempting to bind a 
DDF or data file, the SRDE verifies that the local MicroKernel 
Database Engine is servicing the request. 


Asychronous I/O 


The Server MicroKernel engine for Win32 uses asychronous I/O 
when writing pages to disk. This feature improves performance. The 
MicroKernel quickly writes pages to the Windows system cache. In 
turn, Windows signals when the pages are on disk, helping the 
MicroKernel to perform efficiently for write operations. Read 
performance is also enhanced when there are many concurrent 
operations being done in the MicroKernel at the same time, 
especially if you access your dataset on a striped set of disk drives. 
Each read causes a worker thread to wait until the page is available. 
With asynchronous I/O, the operating system can pool the work of 
multiple readers to make the read operations more efficient. 


The Pervasive.SQL Relational Database Engine (SRDE) provides 
ODBC support for Pervasive.SQL applications. The SRDE now runs 
as a service on Windows NT and as an NLM on NetWare. 
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SRDE platforms include Windows 95/98/NT/NetWare. On 
NetWare, the workstation engine has no user count.The same SRDE 
is included in both the Win32 workstation or workgroup engine and 
NT server engine versions of Pervasive.SQL 20001. On NetWare 
servers, NLM versions of the ODBC communications server, ODBC 
Driver Manager, and SRDE will be provided. 


ODBC client platforms include Windows 95/98/NT. Remote ODBC 
application access to the SRDE requires installation of the ODBC 
Client, which is a specialized ODBC driver that routes client-side 
ODBC calls to the ODBC communications server over the network. 


Win16 ODBC applications running on a Win32 workstation that is 
executing a Pervasive.SQL 20001 engine locally are supported using 
the ODBC thunk mechanism. Thunking with the Microsoft- 
provided ODBC thunk DLLs is required for remote Pervasive.SQL 
20001 engine access from a Win16 ODBC application running on a 
Win32 workstation. 


Features of the SRDE include: 


= Atomic statements 

= Bidirectional cursors (using the ODBC Cursor Library) 

= Outer join support 

= Updatable views 

= ODBC data type support 

= Multiple variable length columns in a table 

The ODBC communications server is a Windows NT service that 
performs the following functions: 

= supports network communication for ODBC Clients 


= routes ODBC calls to the server-side ODBC Driver Manager 
(which, in turn, routes ODBC calls to the SRDE) 


Relational Architectural Overview 





Relational Architectural Overview 


Pervasive.SQL 
2000i Relational 
Architecture: 
Server 


The following diagram illustrates changes in the architectural 
components of Pervasive.SQL 20001's relational ODBC interface for 
the server version. The SQL Connection Manager 
(W3SQLMGR.EXE) starts and runs as a service on Windows NT, as 
an NLM on NetWare, and as a daemon on Unix. 


The SQL Connection Manager for the server consists of one 
executable and three DLL files: 


m W3SQLMGR.EXE - SQL Connection Manager 

= W3MGRMSG.DLL - Message File 

m W3MGRRES.DLL - Resource DLL 

m W3MGRRSX.DLL 

Once the first SQL Connection Manager is opened, it invokes a child 
process of the same service. The child process is used to manage 
requests for 1-25 ODBC connections. If there are more than 25 
connections, the next 25 will be served bya second child process, and 


subsequent connections in increments of 25 processes will be served 
by additional separate connection manager processes. 


The SQL Connection Manager uses the ODBC Driver Manager to 
make calls to the SQL Relational Database Engine (SRDE), which in 
turn rests on top of the MicroKernel. 


This following diagram illustrates the relational architecture of 
Pervasive.SQL 2000i on the client machine. The client talks to the 
SQL Connection Manager on the server through TCP/IP or SPX. 
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Figure 2-1 Pervasive.SQL 20001 Relational Architecture: Client 
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The following diagram illustrates the relational architecture of 
Pervasive.SQL 20001 on a standalone workstation. 
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Figure 2-2 Pervasive.SQL 20001 Relational Architecture: Workstation 
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The following diagram illustrates the relational architecture of 
Pervasive.SQL 20001 in a workgroup computing environment. 





2-9 


Understanding the Pervasive Component Architecture 


Figure 2-3 Pervasive.SQL 20001 Relational Architecture: Workgroup 
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Overview of Smart Components 


Since version 7.0, Pervasive.SQL has offered a new component 
architecture called Smart Components, which improves installation 
and run-time reliability and makes application troubleshooting 
easier. 


In earlier Pervasive Software releases, some developers experienced 
one or more of the following problems: 


= Installation of a new application (with old client Requester 
components) overwrote new Requester components in shared 
locations, causing old applications to fail the next time they ran. 


= Installation of a new workstation engine was incompatible with 
existing client Requesters. Existing client Requesters loaded the 
old engine, failing to provide features required by the new 
application. 

a Difficulty identifying the function, version, and patch level of 
installed components. 


= Difficulty determining the root cause of run-time operational 
failures, especially in client/server operation. 


The Smart Components architecture is designed to reduce or 
eliminate these problems by providing the following features and 
benefits: 


= Component Identification: Component function, major, and 
minor functional level are easily identified to aid in problem 
resolution. 

= Unique Component Naming: Each release ofa given component 
has a unique file name, so that updated versions of a component 
never overwrite previous versions. A Pervasive upgrade will not 
damage existing Pervasive-based applications. 

= Dynamic Binding: Pervasive.SQL no longer loads a fixed set of 
program files into memory. Dependent components are loaded 
only if another component specifically requires its functionality, 
major, and minor functional level. Incompatible components 
are never accidentally loaded, reducing or eliminating version- 
related failures. 

m Pervasive.SQL Event Logging: All components report errors and 
messages to a central log, easing the burden of troubleshooting. 
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Error Code Clarification: Error conditions from underlying 
layers are now logged through to the Pervasive.SQL Event Log, 
rather than hidden within an umbrella status code. Because the 
root causes of certain errors can now be more quickly 
determined, troubleshooting is much easier. 


Component Identification 





Component Identification 


Each component contains a unique embedded Component ID. The 
Component ID is a string containing information such as: 


Designated operating system 
Functionality 

Major functional level 
Minor functional level 

Build site 

Build number 

Timestamp 

Checksum 


Pervasive Software Customer Support representatives can browse the 
file image of a component to locate the Component ID and verify 
that it is the correct component. 
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Unique Component Naming 


Pervasive.SQL components have new unique names that reflect the 
platform, type, and functional level of the component. Each 
subsequent release of a component (even patches) will have a slightly 
different name, so that no two releases of the same functional 
component have the same file name. 


This feature both identifies the exact functionality of a file and 
prevents different versions of a file from overwriting each other 
during installation of a new version or uninstall to a previous 
version. 


Components are named using a well-defined scheme. All 
component names adhere to 8.3 notation for compatibility on 
systems that do not support long file names (such as Windows 3.1). 
The first two characters of the prefix identify the designated run- 
time platform. The next three characters identify the component 
functionality—its type. The sixth character identifies the major 
functional level (hexadecimal, range 1 to F), and the final two 
characters identify the minor functional level (hexadecimal, range 00 
to FE). 


W3MIF100.DLL 
Platform as L j Il ILL | 


Type ~ 
Major Functional Level “———————— 
Minor Functional Level -« 




















The major functional level defines the version of the component, 
which began at one (1) with the first release of Pervasive.SQL. The 
minor functional level begins at zero (0) for each major functional 
level. Whenever the major functional level increments, the minor 
functional level is reset to zero. The minor functional level increases 
with each patch or public release of the component if it contains any 
changes whatsoever. The following tables show the Platform Codes 
and a sampling of Component Type Codes. 


Unique Component Naming 


Table 2-1 Platform Codes 

















Platform Code 
Windows 3.1, Windows for Workgroups (Win16) Wi 
Windows 95, Windows NT (Win32) W3 
Windows NT NT 
NetWare 3.2 and 4.x NW 














Table 2-2 Component Type Codes 











Component Type Code 
Btrieve Interface DLL BIF 
Network Services Layer NSL 
MicroKernel Interface DLL MIF 
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Dynamic Binding 


Rather than load a hard-coded file name, upstream components that 
require the functionality of a downstream component now can 
specify what functionality and what revision they require. An 
upstream component loads before a downstream component. For 
example, the application loads the Btrieve interface component, or 
.BIF. The .BIF then loads the .MIF, or the MicroKernel interface 
module. In this example, the .BIF is an upstream component, and 
the .MIF is a downstream component. 


Upstream components load their downstream components with the 
help of a component called the Abstract OS Services DLL (Services 
DLL). The upstream component provides the Services DLL with a 
binding rule, specifying the type and minimum functional level of 
the required downstream component. Based on the binding rule, the 
Services DLL constructs a file name template and searches for a file 
that can deliver at least the required functionality. When it finds such 
a file, it returns the full path to the calling component, which then 
loads the specified downstream component. 


When the engine is first started, the operating system searches the 
default path for W3BTRV7.DLL and W3SCMV7.DLL. On Windows 
9X, these DLLs are installed into the system directory. 


Once these DLLs are loaded, when looking for additional 
downstream components, Smart Components first explore the 
directory specified in the engine's “InstallInfo\InstallDir” registry 
key. This registry key is written silently during product installation in 
the Pervasive Software registry pathway based on the target 
installation directory. Ifthe requested component is not found in the 
directory specified in the registry, Smart Components then searches 
on the platforms default path. 


The Services DLL employs a best first match search algorithm, 
meaning that it stops in the first directory where it finds an 
acceptable match and then returns the highest minor functional level 
of the specified component that exists in that directory. 


For example, if a component requires W1MIF101.DLL or later, the 
Services DLL searches until it finds an instance of W1MIF1xx.DLL, 
where xx is 01 or greater. Then, the Services DLL searches that 

directory for the instance of W1MIF1xx.DLL with the greatest value 
of xx. This file name is then returned to the calling component. For 


Dynamic Binding 


example, if W1MIF101.DLL and W1MIF102.DLL are present in that 
directory, W1MIF102.DLL is returned. If there is an instance of 
W1MIF103.DLL in a different directory later on the search path, it is 
never reached. 
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Pervasive.SQL Event Logging 


With the release of Pervasive.SQL 7 and greater, the MicroKernel 
message log has been replaced by a new centralized event log. All 
Pervasive.SQL 7 and later components write status and error 
messages to the same log file. In addition, if two or more Pervasive- 
based applications are running on the same machine, they share a 
single event log. 


The event log, called PVSW.LOG (or event.log on Unix), is located in 
the Windows root directory of each machine that is running a 
Pervasive-based application (on Unix, it is located in the bin 
subdirectory of the psal installation directory). This location cannot 
be changed or customized. In the following table, C: represents the 
drive letter where your operating system is installed. 


Table 2-3 Platform Event Log Locations 


























Platform Event log location 
Windows 95/98 and Windows 3.1x CAWINDOWS 
Windows NT CAWINNT 
NetWare SYS:SYSTEM 
Unix -psql/bin 
Syntax The event log consists of ASCII text messages that adhere to the 


following syntax description: 


Table 2-4 Event Log Fields 














Field Length (in Contents 

Bytes) 
Date 10 Automatic date-stamp in mm/dd/yyyy format. 
Time 8 Automatic time-stamp in hh:mm:ss format. 
Component 15 File name of component returning the error 


(prefix only, no extension). 





Process 8 Instance ID of the component, which is either the 
process ID of the component or the thread group 
ID in NetWare. 
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Table 2-4 Event Log Fields continued 














Field Length (in Contents 

Bytes) 
Process Upto 15 Path and name of the component, truncated to 
Name the last 15 characters. 
Computer Upto 15 Name assigned to the machine hosting the 
Name process, truncated to the first 15 characters. 
Type 1 A single character: | for Information, W for 


Warning, or E for Error. 





Category Upto 10 A component-specific text field. Components are 
not required to provide a value in this field. 





Msg ID Up to 8 A numeric message identifier that corresponds to 
a message string within a resource file 
associated with the calling component. 


Message Up to 1,024 The message text which may be either a string 
retrieved from a resource associated with the 
calling component or a text string passed directly 
from the calling component. 

















An entry may be followed by binary data in standard ASCII 
hexadecimal format. There is no limit to the length of the binary 
data. 


Sample Entry The following shows an example of the type of data contained in the 


event log. 
Date Time Component Process Process Name 
11-04-1997 14:01:05 NTMKDE 000000DD  W3DBSMGR.EXE 
Computer Name Type Category Msg ID Message 
LABSERVER | MicroKernel is using 


default settings. 
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In earlier Btrieve and SQL Interface releases, top-level components 
occasionally subsumed error codes from underlying components 
into an umbrella error code returned by the top level component. In 
some cases, this situation could make troubleshooting difficult 
because a single error code could have a wide range of possible root 
causes. 


Starting with Pervasive.SQL 7, most top level components were 
redesigned to pass through error codes from underlying components 
so that the actual source of the error is clearly identified to the calling 
application and/or in the log file. 


In situations where an error code remains overloaded, specific 
information in the Pervasive.SQL event log should identify the root 
cause of the error. 


Diagnosing Load Errors 





Diagnosing Load Errors 


Pervasive.SQL provides the following types of information you can 
use in diagnosing module load errors: 


Status codes. You can refer to the Status Codes and Messages 
manual for more information about the specific status code 
returned. 


Event log. You can look for the following information in the 


Pervasive.SQL Event Log to get additional information about a 
specific module load error: 


Component Name The logical or physical name of the module that received 


the load failure. Logical names used are: 


Serviceslfc—Abstract OS Services 
Btrvlfc—Btrieve 
MKDElfc—MicroKernel 
PSQLIfc—Pervasive.SQL 


The physical name is logged if the calling module 
attempted to load a component using a binding rule. For 
example, a physical name is W3BIF 102. 


Type The type of load error, as follows: 


E (Error)—The module could not be found or an operating 
system-specific error occurred while loading the module. 


W (Warning)—A symbol could not be found or was not 
exported by the module. 


Message The message depends on the type of module load error. If 


the module could not be found, the event log contains the 
binding rule that specified the downstream component. If 

an operating system-specific error occurred, the event log 
contains that operating system error. If a symbol could not 
be found or was not exported, the event log contains that 

symbol. 


On-screen errors. The event log is not functional until the 
Services DLL loads. Therefore, if a load error occurs while 
binding to the Services DLL, the event log does not log the error. 
Instead, Pervasive.SQL can display an on-screen error. 


You must enable the Services DLL to display on-screen module 
load errors by setting the PVSW_DISP_LOAD_ERRS 
environment variable. Its format is as follows: 
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PVSW_DISP_LOAD_ERRS=AIF 


This environment variable should only be set to diagnose 
module load errors. In all other cases, it should not be set. 


To diagnose an error, set this variable as specified and perform 
the operation. The load error is displayed in a message box on 
your system. 


Pervasive Auto-Reconnect 





Pervasive Auto-Reconnect 


Pervasive Auto-Reconnect (PARC) allows client-server or 
workgroup applications to endure temporary network interruptions 
without canceling the current database operation. When 
Pervasive.SQL detects a network interruption, it automatically 
attempts to reconnect at specific intervals for a configurable amount 
of time. This feature also preserves the client context so that when 
communications are re-established, database access continues 
exactly where it left off when the network interruption occurred. 


This feature preserves the application context and attempts to 
reconnect regardless of whether the client or server was attempting 
to send data at the moment when the network communications were 
interrupted. 


When a network interruption occurs, the reconnect attempts occur 
at specific intervals. For all connections, successive attempts are 
made at 0.5, 1, 2, 4, and 8 seconds, continuing every 8 seconds 
thereafter until the AutoReconnect Timeout value is reached. If no 
attempt is successful before the maximum wait time is reached, then 
the current operation fails and the client connection is reset. The 
maximum wait time is configurable between 45 seconds and 65,535 
seconds. 


This feature is disabled by default. For this feature to operate, you 
must select Enable Auto Reconnect (page 4-7) for both client and 
server configurations. You can specify the timeout value using the 
server setting Auto Reconnect Timeout (page 4-7). 


Remarks 


This feature is supported for Btrieve, ODBC, and DTI connections. 
All 16-bit (when thunking to Win32) and 32-bit Windows 
applications are supported, but not pure DOS or Windows 3.x 
platforms. DOS using Btrieve DOS box support on 32-bit Windows 
platforms is supported. This feature is supported on Windows and 
NetWare. 


The Btrieve communication servers may write out *.PAR or *.SAR 
files to the Transaction Log Directory. These are temporary files that 
contain the context for the last item that the server tried to send to 
the client. When a reconnection occurs, the client may ask for data 
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to be re-sent. The server reads these files to obtain the appropriate 
data. These files are normally deleted by the server after the data is 
read or later when the connection is finally terminated. 


Interface Support 


Options for this feature are supported by Distributed Tuning 
Interface (DTD), Distributed Tuning Objects (DTO), and Pervasive 
Control Center (PCC) Configuration program. 


chapter 
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How to Work with the Configuration Utility within PCC 


This chapter covers operating system permissions, network 
topologies, engine configuration, and client configuration. 

= “Configuration Utility Overview” on page 3-2 

m “Special Notes on the Configuration Utility” on page 3-4 
= “Configuration Utility Tips” on page 3-8 


= “Tuning Performance” on page 3-9 
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The Pervasive.SQL 20001 Configuration utility uses a tree control/ 
results pane GUI design. It supports the full functionality of the 
Pervasive.SQL Win32 Configuration utility (configuration of client/ 
server components, remote connection to engines), as well as 
enabling configuration of Win16 components on Win32 operating 
systems. 


The Configuration utility supports the configuration of the ODBC 
communications server and the SRDE. Configuration parameters 
for these components include the following: 


= timeout periods 

= event logging (integrated with NT event viewer) 
m server protocols (including encryption) 

= network interfaces (for multi-homed hosts) 


m port settings 


The Configuration utility manipulates settings for Pervasive.SQL 
2000 Server, Workstation, and Workgroup engines along with any 
local client components (all client components must be configured 
at each individual workstation). 


Configuring these components is optional. If you do not configure 
them, each component loads with default configuration settings. 
The Configuration utility works only with Pervasive.SQL 20001 or 
later. 


You can use the Configuration utility for the following reasons: 


= Your system or your Pervasive.SQL 2000 application requires 
you to adjust the settings. Refer to your application 
documentation for recommended values. If you are running 
multiple applications concurrently, add the recommended 
values together. If you are running multiple applications 
sequentially, use the highest recommended value. 


= You want to optimize the settings so that Pervasive.SQL 2000 
provides the services you need without using more memory 
than necessary. (The stated memory requirements provide 
guidelines for optimizing your computer's resources.) 


Configuration Utility Overview 





Note For some of your changes to take effect, you must shut down and 
restart the Pervasive.SQL 2000 components. For more information, 
refer to Getting Started with Pervasive.SQL. 





The Configuration utility is tightly integrated with the Pervasive 
Control Center and appears as nodes in the Control Center tree. 
Figure 3-1 shows the Configuration utility within the PCC. 


Figure 3-1 Pervasive.SQL Control Center Screen 


E Pervasive.SQL Control Center 
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This section contains information to help you understand the 
Configuration utility, which is described in the following sections: 


= “Ensuring Configuration Changes Take Effect” on page 3-4 
=» “Connecting to Different Machines” on page 3-4 

= “Interpreting Parameter Settings” on page 3-5 

When you start the Configuration utility, it is ready to configure 


client requesters and the engine on the local machine if one is 
present. 


Most engine Configuration parameters require the database engine 
to be reloaded after they have been changed. You can re-load the 
engine in one of two ways: 


= reboot the server 


= stop and re-start the engine as described in Chapter 2 of 
Pervasive.SQL User’s Guide. 


The Configuration utility can configure both local and remote 
engines as well as local client components; however, each engine 
must be configured separately. To configure a particular 
Pervasive.SQL engine: 


1 Open the Pervasive Control Center and double-click 
Pervasive.SQL 2000i Engines. 


If you wish to configure a machine that is not in your engines list, 
it must first added: 


a. Right click on Pervasive.SQL 2000i Engines and select 
Register Engine from the pop-up menu. 

b. Type in the server name or use the browse button to search 
for the desired server. Click OK. 


2 Expand the desired engine and expand the Configuration 
section beneath that engine. 


Interpreting Pa- 
rameter Set- 
tings 


Special Notes on the Configuration Utility 


If you are not logged into the server, you will be prompted to 
enter your user name and password at this time. You must have 
administrator-level rights on the remote machine or in the 
domain (if you are logging into the domain) in order to view or 


change the engine configuration options. 


3 Expand all available options beneath Configuration. The 


options available will vary depending on the platform of the 


engine you are trying to configure. 


When you are connected to a remote machine, you can view and 
change only engine components. Client components (such as on 
workgroup and workstation engines and client machines) can only 
be configured locally on each machine. 





~ Note If you have engines registered that are not running, you may 
encounter delays in PCC as it periodically attempts to contact these 
engines. To eliminate the delay, unregister the “dead” engines. You can 
minimize the delay by performing the following procedure: 


In PCC, right-click Pervasive.SQL 2000 Engines and choose 
Properties. Set Poll interval (seconds) to 999. Click OK. You can also 
disable polling completely by clearing Enable service state polling on 
the same panel. 





Under each option, there are a number of parameters, which are 


displayed in the following table: 


Table 3-1 Parameter Settings 





Name 


The name of the parameter. 





Type 


Defines the value type. The different types are: 
@ Numeric 

@ Bool(ean) 

@ String 

@ Multisel(ect) — choose several values from a given list 
+ 


SelectOne — must choose one value from a given list 





Value 


Shows the current setting. 





Units 








If the value is numeric, this field explains any specific units of 
measure, such as KB or seconds, if required. 
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A 


~ Note If you cannot find information about a particular Configuration 
setting, click on the Find Setting icon on the tool bar. Enter the name 
of the desired setting and a list of case matches is displayed. You can 
display the setting information by clicking on the desired setting. 





The following table outlines the functionality of the Configuration 


utility: 


Table 3-2  Pervasive.SQL Win16, and Win32 Configuration Utilities 





Configuration utility 


Components that it configures 


Transactional 
Access: Where 
Changed 


Relational 
Access: Where 
Changed 





Win32 Configuration 
utility 


(Runs on Windows 9x/ 
NT/2000 workstations or 
Windows NT/2000 
servers.) 


Win16 Configuration 
utility 


(Runs on Windows 3.11, 
Windows 9x/NT/2000 
(using Thunking) — 
Transactional access 
only) 





Local Win32 components 


Windows Registry 
on local machine 


Windows Registry on 
local machine 





Local Win16 components 


BTI.INI on local 
machine 


ODBC.INI on local 
machine 





Windows NT/2000 Server 
components (local or remote 
machines) 


NetWare Server components 
(remote machines only) 


Unix Server components 
(remote machines only) 


Local Win16 components 
Windows NT/2000 Server 


components 
(remote machine only) 


Windows Registry 
on Windows server 


BTI.CFG on 
NetWare server 
bti.ini on Unix server 
BTI.INI on local 
machine 

Windows Registry 


on Windows NT 
server 


Windows Registry on 
Windows server 


ODBC.INI on 
NetWare server 


odbd.ini on Unix 
server 


No 16-bit relational 
access 


No 16-bit relational 
access 





NetWare Server components 
(remote machines only) 


BTI.CFG on 
NetWare server 


No 16-bit relational 
access 





Unix Server components 
(remote machines only) 








bti.ini on the Unix 
server 





No 16-bit relational 
access 
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For each parameter appearing in Configuration, you can double- 
click the parameter to see a window showing the minimum, 
maximum, default, and current value of the parameter. 





Windows 2000 
and Restricted 
Users 


Special Notes on the Configuration Utility 


In Windows 2000, a Restricted user is unable to change most of the 
Client settings in Configuration. In the case of Restricted users, only 
the administrator can modify the configuration options to ensure 
complete security. The only setting a Restricted user is allowed to 
change is Client | Access | Gateway Durability. This setting is 
interactive and requires the user to reset it when new servers become 
available. 


In Windows 2000, a user must log on as at least a Power user to be 
able to fully control their Pervasive.SQL client configuration. 


Please see http://www.microsoft.com for more information about 
Restricted users. In Windows 2000, the client settings are unavailable 
to Restricted users because this type of user is not permitted to make 
modifications to Registry keys in HKEY_LOCAL_MACHINE. 


Most of the Pervasive.SQL client settings are added to this Registry 
key. However, the Gateway Durability setting is kept in 
HKEY_CURRENT_USER, a section of the Registry which can be 
accessed by Restricted users. 


In order to support Windows 2000 Restricted users, Pervasive.SQL 
also keeps the Server Address Table (SAT) keys in 
HKEY_CURRENT_USER instead of HKEY_LOCAL_MACHINE. 


These keys are not configurable settings, but are saved dynamically 
by the client to remember how it successfully connects to the 
server(s). If the client is upgrading to Service Pack 2a from a prior 
version of Pervasive.SQL, the SAT keys found in 
HKEY_LOCAL_MACHINE will be read the first time the client is 
started. The client then writes this information to its new location in 
HKEY_CURRENT_USER. From then on, the client reads and writes 
the SAT keys only in HKEY_CURRENT_USER. 
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The next chapter describes the configuration options available for 
Pervasive.SQL 20001. These options are described as they appear in 
the default view and not the legacy Component View, which view the 
component parameters in a form similar to that found in 
Pervasive.SQL v7. To ensure the Configuration utility is set to default 
view: 


1 Click the Configuration node of the desired engine or client and 
click View on the toolbar. 


2 Make sure Component View is not checked. 


There is also an optional helper pane that provides basic information 
about each setting. To view the helper pane: 


1 Click any configuration folder beneath the Configuration node 
of the desired engine or client, and click View on the toolbar. 


2 Make sure Show Helper Pane is checked. 





Note While working with the configuration settings, if you wish to 
find a particular setting, click on the Find Setting icon on the tool bar. 
Enter the name of the desired setting and a list of case matches will be 
displayed. You can display the setting information by clicking on the 
desired setting. 
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Spotting Perfor- 
mance Bottle- 
necks 


This section provides some general tips on how to maximize 

performance on the initial database connection and on runtime 

operations. While we can offer some general guidelines, the 

performance of any specific application is dependent on a great 

number of factors, including but not limited to the following: 

= network bandwidth and utilization 

= coding techniques in the application 

m free disk space 

= available memory 

m processor speed 

= application(s) usage patterns (write-heavy, read-heavy, 
transactions used/not used, small record size, large record size, 
complex queries, simple queries, ODBC, Btrieve only, and so on) 

= unrelated applications competing for CPU cycles 

m database engine configuration parameters 

As you can see, the engine configuration plays a relatively limited role 

in the overall performance of any given application. Further, the 

database engine dynamically manages a variety of resources based on 

usage patterns. It tunes itself to your environment as needed. The 


sections provided below are offered only as helpful guidelines and 
are not a guarantee of any specific level of performance. 


You can use Monitor to expose performance bottlenecks related to 
certain database engine configuration parameters. To start Monitor, 
choose Start | Programs | Pervasive | Pervasive.SQL 2000i | Utilities 
| Monitor. 


Relating Monitor Displays to Configuration Parameters 


Two different Monitor menu selections display performance 
readings related to configuration parameters: 


= MicroKernel | Resource Usage 


= MicroKernel | Communications 
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The table below shows which configuration parameters correspond 
to the readings displayed in the Resource Usage window: 


Table 3-3 Monitor Resource Usage Corresponding Configuration Settings 








This performance ... corresponds to this parameter in Configuration: 
display ... 
Files None. Formerly “Maximum Open Files,” now 


managed dynamically by the database engine. 





Handles None. Formerly “Logical File Handles,” now managed 
dynamically by the database engine. 





Clients None. Formerly “Active Clients,” now managed 
dynamically by the database engine. 





Worker Threads “Number of Worker Threads (Windows/Unix server 
engines only)” on page 4-25. This setting is still 
available, but the MicroKernel spawns additional 
worker threads as necessary. 














The table below shows which configuration parameters correspond 
to the readings displayed in the Communications window: 


Table 3-4 Monitor Communications Corresponding Configuration Settings 





This performance ... corresponds to this parameter in Configuration: 
display ... 





Communications Threads | “Communications Threads” on page 4-22. 





Total Remote Sessions “Number of Sessions” on page 4-4. 














Interpreting the Displays and Taking Action 


You can make use of the information displayed in Monitor. Monitor 
displays three pieces of information about each type of resource. For 
example, the Worker Threads display shows: 


= Current. The current number of actual worker threads 
operating. 

m Peak. The highest number of actual worker threads that have 
been used since the engine was started. 


= Maximum. The maximum number of worker threads allowed. 


If the Peak value for a resource is the same as the Maximum value, 
then you may want to use Configuration to increase the Maximum 


Before You 
Modify Config- 
uration Param- 
eters 


Minimizing Ini- 
tial Connection 
Time 
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value for the resource, thus allowing the database engine to allocate 
additional instances of that particular resource when it needs to. 


The sections below assume the following: 


mun. 


Pervasive Control Center (PCC) is already open. 


If you need assistance with this task, see “An Overview of 
Pervasive Control Center” on page 3-2 of Pervasive.SQL User's 
Guide. 


You have already registered (if applicable) the engine you wish to 
configure. 


If you need assistance with this task, see “Registering or 
Removing a Server” on page 3-4 of Pervasive.SQL User's Guide. 


You have already double-clicked on the icon representing the 
given engine. For the Server configuration settings, you have 
double-clicked Server or for Client configuration settings, you 
have double-clicked Client. 


You have appropriate operating system privileges to configure 
the given engine. 


If you need assistance with this task, see “Granting 
Administrative Rights for the Database Engine” on page 2-6 of 
Pervasive.SQL User's Guide. 


You must re-start the database engine after making 
Configuration changes to the engine parameters. 


The theory underlying minimal connection time revolves around 
three requirements. These requirements are summarized below, and 
detailed procedures follow: 


Known communications protocol. You do not want the client or 
server to spend additional time trying to connect via protocols 
that are not supported in your environment. By removing client/ 
server support for unavailable protocols, you prevent the 
networking components from trying to use them. 


Known location of database engine. You do not want the client to 
attempt to connect to an engine that does not exist. By specifying 
Workstation-only or Server-only support, as appropriate, you 
prevent the client from timing out while attempting non- 
existent connections. In environments where you have both 
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unshared and shared databases, you can use Gateway Durability 
to force the database engine to keep track of machines where no 
database engine is running, so that it never attempts to connect 
to an engine on these machines, but uses another method to 
access the data. 


= Database engine ready to execute. When a sleeping engine 
receives a new connection request, it takes time to re-allocate 
resources and return to a runtime state. If connection speed is 
more important than resource usage on the server, you can 
prevent the server engine from sleeping when it is not in use. 


Client Parameters 


You must be at the client machine to change the client parameters. 
You must change the parameters at each workstation whose settings 
you wish to change. 


»> To minimize client-side connection delays 


1 In Configuration, click on Client | Communication Protocols. 
Double click Supported Protocols. 


2 In the protocol selection window that appears, select the 
protocols that you are not using in the box labeled “Selected.” 
Click < to move the protocols into the box labeled “Available.” 


3 Click OK. You have now prevented the client from attempting to 
communicate on protocols that are not supported. 


4 Click on Client | Access. If you are using only a remote Server or 
Workgroup engine, double-click Use Local MicroKernel Engine 
and set it to Off. 


If you are using only a local Workstation engine, double-click 
Use Remote MicroKernel Engine and set it to Off. 


If you sometimes use a Workstation engine and you sometimes 
connect to a Server engine or a remote Workgroup engine, you 
must leave both settings On. 


In such a mixed environment with shared and unshared data, 
you can set Access | Gateway Durability to On at each client. 
This setting forces the client software to keep a list of the names 
of any machines on which it is unable to connect to a database 
engine. In order for the client software to determine no engine 
exists on a given computer, it waits for all of its network protocol 
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requests to time out. If your data is stored on a server that does 
not have a Pervasive database engine on it, and you have Access 
| Use Remote MicroKernel Engine set to Yes, the client must 
time out at least once to discover that there is no engine on that 
machine. Gateway Durability ensures that this timeout only 
happens the first time your application tries to access that data. 





Note Using Gateway Durability fixes the network topology. If you later 
install a Server or Workgroup engine on the remote computer, you 
must turn off Gateway Durability on each client so that the list of 
computers without database engines is deleted (thus allowing you to 
connect to the new database engine). You may turn Gateway Durability 
back on immediately, but it starts with an empty list. 





5 Click OK. You have now prevented the client from attempting to 


connect to any database engine types that are not in use. 


Server Parameters 


» To minimize server-side connection delays 


1 


2 


In Configuration, click on Server | Communication Protocols. 
Double-click Supported Protocols. 


In the protocol selection window that appears, select the 
protocols that you are not using in the box labeled “Selected.” 
Click < to move the protocols into the box labeled “Available.” 





Note Be sure that at least one protocol you have selected in the Server 
configuration is the same as selected in the Client configuration. Your 
client and server cannot communicate if they are not using the same 
protocol. 





3 Click OK. You have now prevented the server from attempting to 


communicate on protocols that are not supported. 


4 This step does not apply to database engines on NetWare. Click 


on Server | Memory Usage. Double-click Allocate Resources at 
Startup. Set the value to On. 
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You have now specified that the database engine should allocate 
all necessary memory when it starts up, rather than when the 
first connection request comes in. Choosing this value requires 
more memory, but from the client perspective allows the engine 
to become operational faster. 


5 This step does not apply to database engines on NetWare. 
Double-click Back to Minimal State if Inactive. Set the value to 
Off. 


You have now specified that the database engine should not 
release resources back to the operating system if the engine is 
inactive. All resources remain allocated and ready for use at the 
next client connection. 


6 Click OK. You must re-start the Server engine for these changes 
to take effect. 


Maximizing The theory behind maximum throughput relies on too many 
Runtime variables to list here. Several of the most significant factors are: 
Throughput = Adequate physical memory. If your host system has too little 


RAM, the system spends most of its time and CPU cycles 
swapping memory to disk and back, as different users and 
processes compete for limited resources. 


ms Adequate CPU capacity. If your CPU cannot keep up with the 
inflow of data processing requests, application performance 
suffers. 


m Adequate network bandwidth. If your network is slow or suffers 
from a high collision rate, the database engine may sit idle 
between data access requests, while each client seems to display 
poor performance. 


m Minimal disk I/O. Disk I/O is significantly slower than memory 
I/O. You want to avoid accessing the disk as much as possible, by 
having sufficient cache. 


= Adequate resource allocations. Even with massive physical 


memory available, database performance may suffer if database 
engine configuration parameters are set artificially low. 


In the end, optimal performance is a balancing act among network 
bottlenecks, disk I/O bottlenecks, memory bottlenecks, and CPU 
bottlenecks. This section provides some guidelines on how to reduce 
memory and disk I/O bottlenecks. 
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Ensuring Adequate Physical Memory and Database 
Cache 


Ideally, your database engine should be able to allocate enough 
memory to cache in memory full copies of every database it hosts, 
thus avoiding as much disk I/O as possible. Obviously, caching one 
or more entire databases is not practical in some situations, 
particularly when database size is very large. In addition, such 
measures as adding RAM to the machine only improve performance 
if the existing system resources are heavily loaded under normal 
usage. 


The database engine dynamically selects a cache value when it starts 
up the first time. However, this value is based on available memory 
and may not be the ideal amount of cache for your environment. 


»> To calculate the ideal size of the database memory 
cache 


1 Start by adding up the file sizes of all the data files serviced by the 
database engine. 





Note If you have more than one database serviced by the engine, but 
they are never used at the same time, add up the file sizes of just the 
largest database. 


For example, assume there are two databases on your server, 
with the following file sizes, and users access both databases at 
the same time: 


























The sum of all these files is 1,430 MB. 


2 Add 5% for overhead: 1,430 * 1.05 = 1,501.5 MB, or 
1,574,436,864 bytes. 





Database A Database B 

file1.mkd 223 MB Afile.mkd 675 MB 
file2.mkd 54 MB Bfile.mkd 54 MB 
file3.mkd 92 MB Cfile.mkd 318 MB 
file4.mkd 14 MB 
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The number you have now is the maximum amount of memory 
that the database engine would use if it cached all its hosted data. 
This number can be referred to as MaxCache. 





Note File pages are only written to the database cache when they are 
accessed. Thus, for a database engine to use MaxCache amount of 
memory requires every page in the database to be accessed. This system 
of estimating assumes a long-term steady state for database usage. If 
you bring the database engine down nightly or weekly, it may be 
unlikely that the database engine would access every page in the 
database within the given period of uptime. 


If this situation applies to you, you may wish to estimate the average 
number of distinct pages that your application accesses within the 
given uptime period, multiply that by the page size, and obtain a more 
realistic value of MaxCache for your particular uptime scenario. 





> To determine how much total physical memory you 


1 


2 


3 


need 


As a general rule of thumb, your database cache should not take 
up more than 40% of the memory available on the server. Thus, 
the ideal amount of total physical memory is at least 
MaxCache * 2.5. 


Continuing the example above, the calculation would yield 
3,936,092,160 bytes or about 4GB total physical memory. 


If you have at least 2.5 times your calculated MaxCache memory 
installed on your server machine, open Configuration and set 
Server | Performance Tuning | Cache Allocation Size to the 
calculated value of MaxCache. Then restart the database engine. 


If you can easily add enough memory to reach 2.5 times 
MaxCache, you should consider doing so. 


After upgrading the memory, open Configuration and set Server 
| Performance Tuning | Cache Allocation Size to the calculated 
value of MaxCache. Then restart the database engine. 
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4 Ifitis not practical to add enough memory to reach 2.5 times 
MaxCache, then you may wish to settle for a smaller cache and a 
somewhat greater level of disk I/O. Many applications will run 
almost as fast as 100% cached if the database is at least 25-30% 
cached. The specific performance ratio is dependent on the 
design and average usage model of the application. 


5 Inall cases, you should set Server | Performance Tuning | Cache 
Allocation Size as high as you can but not more than MaxCache 
and not more than about 40% of physical memory. If MaxCache 
for your databases is greater than 1.6 times your physical 
memory, consider adding additional RAM. 


Depending on whether the database engine was previously memory- 
constrained, you may see a significant performance gain, a marginal 
performance gain, or none. 


Minimizing Disk I/O 


Reading and writing data to/from disk is much slower than reading 
and writing to/from memory. Thus, one way to optimize 
performance is to minimize disk activity. 


An important consideration in your attempts to minimize disk I/O 
is recoverability of data. Disk I/O is a direct trade off against 
transaction durability and recoverability. The more data you keep in 
memory without pausing to log changes to disk, the faster the 
database performs. On the other hand, the more data you keep in 
memory without pausing to log changes to disk, the more data you 
lose if the system experiences a failure. 


» To reduce disk I/O 


1 As discussed in the previous sub-section on page 3-15, 
“Ensuring Adequate Physical Memory and Database Cache,” 
one of the most important considerations is to ensure you have 
enough database memory cache to avoid frequently swapping 
data pages between disk and cache. See that section for details. 


2 The next step is to consider how much logging you require and 
what quantity of database operations you are willing to lose in a 
system failure. The greater the quantity of changes you are 
willing to lose, the more you can risk in the pursuit of 
performance. 
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<4 


3 


4 


5 


Using Archival Logging and Transaction Durability both require 
log files. By default, archival logging is turned off. Turn it on only 
if you perform regular backups and you need the capability to 
restore data up to the moment of a system failure. When you 
specify the files to be logged, be sure to specify only the files for 
which you absolutely must have logging. See Chapter 8, “Backup 
and Restore,” for more information. 


By default, transaction durability is turned on. Turn it off only if 
you don't use transactions and your database consists of a single 
data file. Also check with your application vendor to be sure they 
allow the application to run without transaction durability. 





Caution The consistency of any multi-file database cannot be 
guaranteed if transaction durability is disabled. 


If you have any logging features turned on, you can specify how 
much data the engine stores in memory before writing to disk. 
This feature is important because the changed data builds up 
over time. The more log data you allow to build up in memory, 
the less frequent the disk writes are. 


The setting Server | Performance Tuning | Log Buffer Size 
specifies the number of bytes of database operations that the 
engine stores in memory before writing them out to the log files. 


If a system failure occurs, the data in the log buffer is lost. 


If you have transaction durability turned on, you can specify the 
maximum size of the log segments on disk. Specifying a larger 
log segment size can improve performance slightly, because 
fewer log segments have to be created and closed over time. 


The setting Server | Performance Tuning | Transaction Log Size 
specifies the maximum number of bytes that can be stored in a 
log segment before closing it and opening a new segment. 


If your application usage is weighted heavily in favor of database 
read operations, you can increase performance by turning on 
Server | Performance Tuning | Index Balancing. Over time, 
index balancing reduces the number of nodes on the average 
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index page, allowing read operations to occur faster. However, 
for insert, update, and delete operations, additional time and 
disk I/O may be required because the engine balances the index 
nodes across adjacent pages. 


Be sure that tracing is turned off, both in the MicroKernel and/ 
or at the ODBC level. Tracing may cause a significant reduction 
in performance because it can introduce a large amount of disk 
I/O. 


To ensure ODBC tracing is turned off, choose Start | Programs | 
| Pervasive | Pervasive.SQL 2000i | Utilities | ODBC 
Administrator and click on the Tracing tab. If tracing is off, you 
should see a button labeled “Start Tracing Now,” and you should 
click Cancel. If tracing is on, click Stop Tracing Now, then click 
OK. 


To ensure MicroKernel tracing is turned off, use Configuration 
to inspect the setting Server | Debugging | Trace Operation. Set 
the value to Off if it is not already. 


Ensuring Adequate Resource Allocation 


If your database server platform has adequate memory and CPU 
power, you should ensure that your database engine can take full 
advantage of the available hardware resources to service multiple 
clients and multiple data files most efficiently. 


> To configure multiple client and file handling 


1 


The setting Server | Performance Tuning | Communications 
Threads allows you to specify how many threads are available to 
handle client connections. 


For any network with up to 32 client workstations, you should 
assign one communications thread for each connected 
workstation. Above 32 clients, you should use Monitor to 
evaluate whether the peak usage is hitting the maximum 
allowed. See “Spotting Performance Bottlenecks” on page 3-9 
for more information. 


After you increase the maximum value and restart the database 
engine, wait until a period of peak usage has occurred, then 
evaluate the situation again using Monitor. 
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2 


The setting Server | Performance Tuning | Number of Input/ 
Output Threads allows you to specify how many threads are 
available to handle file operations. 


As a guideline, the value of this setting should be about 1/8 the 
number of files the application has open, on average. For 
example, if the application has 40 files open most of the time, 
I/O Threads should be set to 5. 


Using Monitor, choose MicroKernel | Resource Usage from the 
menu. In the window that appears, the Files: display shows you 
current and peak number of files open. You can generate an 
average reading by recording several Current values over time. 
Then you can specify an appropriate setting for I/O Threads 
based on the average value. 


Server engines only: If you always have a large number of clients 
running on the same computer as the server engine, you may 
wish to increase the value of Performance Tuning | Number of 
Worker Threads (Windows/Unix server engines only). The 
database engine spawns additional threads as needed, but this 
value specifies how many it initially allocates. 
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Configuration Settings Available in Pervasive.SQL 20001 


This chapter discusses the following topics: 


m “Server Configuration Parameters” on page 4-2 
m “Win32 Client Configuration Parameters” on page 4-31 


=» “Win16 Client Configuration Parameters” on page 4-38 
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Server Configuration Parameters 


Access 


Every Pervasive.SQL engine has server configuration options, 
including the Workstation and Workgroup engines. This section 
describes the different configuration options available for 
Pervasive.SQL engines. 


Accept Remote Request (Windows/Unix engines only) 


Name Type Range Default Units 
Accept Remote Request Boolean On/Off On N/A 


This setting specifies whether the Communications Manager accepts 
requests from remote servers and client workstations. If you turn this 
option to On, the Communications Manager advertises its presence 
on the network. 


Active Clients 


Name Type Range Default Units 
Active Clients Numeric 1 - 65535 Dynamic N/A 


This setting is no longer used by the MicroKernel. The client list is 
allocated dynamically and is limited only by the memory in the 
computer. Each client requires 308 bytes. By default, this setting is 
dynamically managed by the database engine. Pervasive 
recommends that you use the default behavior. 


Authentication (Unix engines only) 


Name Type Range Default Units 


Authentication SelectOne Three options. Emulate Workgroup N/A 
See below Engine 


This option specifies which type of authentication to use for access 
to the server engine. The available options are: 


= Emulate Workgroup Engine. Use this value when Samba is used 
to authenticate user access on the system. 
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= Proprietary Authentication (using btpasswd). Use this value 
when not using Samba and the user does not have an account on 
the server. This allows a separate password file to be maintained 
when connecting to the Unix system. 


= Standard Unix Authentication. Use this value when not using 
Samba but users have accounts on the Unix system. 


Configuration File (Unix engines only) 


Name Type Range Default Units 
Configuration File String N/A /etc/smb.comf N/A 


This setting specifies the location of the smb.conf file used by Unix 
to export local file systems to Windows clients. The engine requires 
this file to translate UNC paths on remote systems into local calls to 
the correct database file. 


The default value is /etc/smb.conf. If you installed the Samba 
configuration file in a different location, enter the correct path and/ 
or file name. 


Load brouter (NetWare engines only) 


Name Type Range Default Units 
Load brouter Boolean On/Off Off N/A 


This setting controls whether the Message router (BROUTER.NLM) 
is loaded during the execution of the BSTART command. The 
Message Router allows other applications running as NLMs on the 
server (such as the SQL Interface) to communicate with remote 
servers on which the MicroKernel is loaded. To access data on a 
remote server, set this option to On. 


Logical File Handles 


Name Type Range Default Units 
Logical File Handles Numeric 1 - limited by Dynamic N/A 
memory 


This setting is no longer used by the MicroKernel. The file handle list 
is allocated dynamically and is only limited by the memory in the 
computer. Each handle uses 256 bytes of memory. 
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Maximum Databases 


Name Type Range Default Units 
Maximum Databases Numeric 1 - limited by Dynamic N/A 
memory 


This setting is no longer used by the MicroKernel. The open database 
list is allocated dynamically and is only limited by the memory in the 
computer. Each open database uses 810 bytes. 


Maximum Open Files 


Name Type Range Default Units 
Maximum Open Files Numeric 1 - 64000 Dynamic N/A 


This setting is no longer used by the MicroKernel. The open file list 
is allocated dynamically and is only limited by the memory in the 
computer. Each open file requires 2,398 bytes. The MicroKernel 
maintains file information for each file as long as there is an active 
client handle to that file or a page in cache for that file. 


Number of Sessions 


Name Type Range Default Units 
Number of Sessions Numeric Windows: O - limited by 500, but N/A 
memory dynamic on 
Win32 


NetWare/Unix: O - 4906 


This setting specifies the maximum number of network connections 
that can access the server at any given time. You cannot improve 
performance by specifying a value higher than you need. 


The available options are: 


= Windows NT: 0 through the upper limit of your system memory. 

m NetWare: 0 to 4,906 sessions. You can have the same number of 
sessions for each protocol. For example, if you set this to 10, you 
can have 10 SPX and 10 TCP/IP sessions, making a total of 20 
sessions. 


= Unix: 0 to 4,906 
The actual number of sessions may be limited by the amount of 


memory in the individual machine, because each session requires 2 
kilobytes. If you have multiple applications running on one client, 


Communica- 
tion Buffer Size 
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each application may generate one or more sessions to the 
MicroKernel. 


On Win32 platforms, this default value is adjusted based on the 
maximum number of users reported by the user count manager. The 
engine starts with a default value equal to five times the installed user 
count, then adjusts that number so that it is between 100 and 1000, 
inclusive. The current value as read from the registry is adjusted to 
100 if it is less than the calculated number. If the calculated value is 
different than the value in the registry, the calculated value is written 
to the registry. Note that Win32 systems that currently have the old 
default value of 15 will get replaced by 100. 


Brouter Communication Buffer Size (NetWare only) 


Name Type Range Default Units 
Brouter Communication Numeric 1024 - 65153 16384 bytes 
Buffer Size 


This setting specifies the maximum length of the user data that any 
local server MicroKernel application can access at a remote server via 
BROUTER. Specify the length of the user data in bytes. Specifying a 
value higher than you need does not improve performance and may 
waste memory. 


The actual buffer size may be limited by the amount of memory in 
the individual machine, because the memory requirement for this 
option is equal to (buffersize + 355) * 4 bytes. 


Communication Buffer Size 


Name Type Range Default Units 
Communication Numeric Unix: 1024 - 65149 65149 bytes 
Buffer Size NetWare: 512 - 65116 65116 

Win32: 1024 - 65153 64512 


This setting specifies the size of the buffer that the Btrieve 
communications layer allocates for database requests from remote 
clients. This value should be at least as large as the largest data length 
parameter for your Btrieve Requester. This value should be the same 
as the value of MKDE Communications Buffer Size. 
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MKDE Communication Buffer Size 


Name Type Range Default Units 
MKDE Communication Numeric Unix: 1024 - 65149 65149 bytes 
Buffer Size NetWare, Win32: 1024 - 64512 

65153 


This setting specifies the length in bytes of the longest block of data 
that can be transferred between an application running on the server 
and the MicroKernel server engine. Each worker thread allocates a 
memory buffer large enough to accommodate this maximum length 
of data. (A message is a unit of related data that the MicroKernel or 
the application passes over the network.) 


Setting a value higher than you need does not improve performance. 





Note System Administrators: Refer to the documentation for your 
Pervasive.SQL application to get an appropriate value for this option. 
If you use multiple applications, use the largest value. 





Read Buffer Size (Windows/Unix engines only) 


Name Type Range Default Units 
Read Buffer Size Numeric 4096 - 65536 4096 bytes 


This setting specifies the size of the buffer that the MicroKernel uses 
to read packets from the operating system’s communication layer. 
Any value you enter is rounded up to the nearest multiple of the 
system page size (4096 bytes on Intel platforms) at the time that the 
engine allocates the buffer. 


You should set this option equal to the Communications Buffer Size 
plus an allowance for system overhead (about 400 bytes). However, 
be aware that setting this option to a higher value than the default 
carries a memory penalty, because the system allocates a buffer of the 
specified size for each active remote client connection. For example, 
if you have 100 active remote clients and you have the buffer size set 
to 4 KB, the system allocates 400 KB of memory. If you have the 
buffer size set to 16 KB, the system allocates 1600 KB of memory. 


Communica- 
tion Protocols 
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Receive Packet Size (NetWare engines only) 


Name Type Range Default Units 
Receive Packet Size Numeric 532 - 4096 1500 bytes 


This setting only applies to the SPX protocol and specifies the size of 
the individual network packets this component receives. For the 
approximate memory required, the number of receive packets can 
grow dynamically during execution, but starts with the number 
indicated. 


To determine the proper value for your system, use the following 
formula: 


Number of receive packets * Receive packet size 
where Number of receive packets = (Communications Buffer Size / 
Receive packets) + 1, or 45, whichever is greater 


The default Receive Packet Size varies depending on your network 
card and hardware capabilities. If you are using the Win32 client 
Requester on an Ethernet topology, use the default value for this 
option. If you are on a Token Ring topology, set this value to 4,096 bytes. 
Setting the value too low may result in workstation hangs or a Status Code 
95, “The session is no longer valid.” 


Auto Reconnect Timeout 


Name Type Range Default Units 
Auto Reconnect Timeout Numeric 45 - 65535 180 seconds 


This setting specifies how long the client will attempt to connect to 
the server before giving up. When a AutoReconnect-enabled client 
first connects to a AutoReconnect-enabled server, the server 
communicates this value to the client so that both components know 
how long to attempt to reconnect in the event of a network 
interruption. 


Enable Auto Reconnect 


Name Type Range Default Units 
Enable Auto Reconnect Boolean On/Off Off N/A 


This setting specifies whether you want the server to support clients 
attempting to auto-reconnect during a network outage. A setting of 
“On” means AutoReconnect is enabled. 
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Auto Reconnect is not in effect for a given client connection unless 
this setting is also enabled in that client's configuration. 


Listen IP Address 


Name Type Range Default Units 
Listen IP Address String Any valid IP 0.0.0.0 N/A 
address 


This option specifies the IP address the MicroKernel listens on when 
TCP/IP Multihomed is Off, and two network cards are present. 


NetBIOS Port (Windows engines only) 


Name Type Range Default Units 
NetBIOS Port Numeric 33 - 254 66 N/A 


This option specifies the NetBIOS port the MicroKernel listens on. 


ODBC Connection Mgr Supported Protocol 
(Server engines only) 


Name Type Range Default Units 


ODBC Connection Mgr SelectOne TCP, SPX TCP N/A 
Supported Protocol 


This option determines which protocol the SQL Connection 
Manager uses. 


Supported Protocols 


Name Type Range Default Units 
Supported Protocols Multiselect See below Varies N/A 


This setting specifies the protocols that are used by the 
Communications Requester. If more than one protocol is specified, 
the Communications Requester attempts to connect on each 
available protocol. The first protocol to connect is then used for the 
remainder of the session. The default value varies depending upon 
the platform; the available options are: 
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Table 4-1 Server Supported Protocols 


@ Microsoft SPX @ Novell IPX 

@ Microsoft SPXII @ IBM TCP/IP 

@ Microsoft IPX + IBM NETBIOS 

@ Microsoft TCP/IP @ NWIPX/XPS SPX 
@ Novell SPXII @ Microsoft NetBIOS 





~ Note You must have at least one specific protocol that is enabled at 
both the client and the server, or else they cannot communicate. 





TCP/IP Multihomed 


Name Type Range Default Units 
TCP/IP Multihomed Boolean On/Off Off N/A 


This options specifies whether the MicroKernel should listen for 
client connections on all Network Interface Cards. If it is set to On, 
the IP address listed in the Listen IP Address option is ignored. 





"Note For Unix servers, Multihomed is the default and there is no way 
to override or change the behavior. 





The default value is set to Off to enable all pre-SP2a clients using 
TCP/IP to connect to a Pervasive.SQL 2000 v7.82 (or later) server. To 
enable the multihomed capability, the administrator must change 
this setting to On, after upgrading all client requestors to 
Pervasive.SQL 2000 v7.82 (SP2) or later. 





Note Older versions of the requesters cannot connect via TCP/IP to a 
Windows server engine configured with TCP/IP Multihomed setting 
On. 
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TCP/IP Port (Server engines only) 


Name Type Range Default Units 
TCP/IP Port Numeric 256 - 65535 1583 N/A 


This setting configures the port number that the SQL 
Communications Manager listens on. 


This port number must be the same as that defined in any Client 
DSNs pointing to this server. For information on how to change the 
port number in a Client DSN, see “Client DSN Options” on page 5- 
7. The Btrieve interface port is 3351, and is not configurable. 


Use SAP (NetWare only) 
Name Type Range Default Units 
Use SAP Boolean On/Off Off N/A 


This setting specifies whether the Btrieve Communications Manager 
should use the Service Advertising Protocol (SAP). This setting 
applies to SPX communications only. 


Create File Version 


Name Type Range Default Units 
Create File Version SelectOne 5.x - 7.x 7.X N/A 


This setting specifies the format in which all new files are created. 
The 7.x MicroKernel can read files created in 5.x and 6.x versions of 
the MicroKernel. In addition, the 7.x version can write to files using 
the existing file format. In other words, it writes to 5.x files using the 
5.x file format, writes to 6.x files using the 6.x file format, and writes 
to 7.x files using the 7.x file format. 


Specify 5.x or 6x only if you need backward compatibility with a 
previous version of the MicroKernel. Specifying 5.x or 6.x does not 
affect any existing 7.x files. 


Data Integrity 
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System Data 


Name Type Range Default Units 
System Data SelectOne See below If needed N/A 


System data refers to a hidden unique key in each record. Because the 
MicroKernel relies on uniquely identifying rows in order to ensure 
transaction durability, a file must either have a unique key defined or 
have system data included in the file. The default value is If needed; 
the available options are: 


= None. By default, system data is not included on file creation. 
Application developers using the Create operation can override 
this setting. 

= If needed. System data is added to the file on file creation if the 
file does not have a unique key. 

= Always. System data is always added on file creation, regardless 
of whether the file has a unique key. 





Note The System Data setting does not affect existing files. This setting 
only affects how new files are created. 


If you want to use transaction durability with a file that was not created 
with System Data turned on and does not have a unique key, you must 
re-create the file after setting System Data to Yes or If needed. 


Even if a file has a unique key, you may want to include system data, 
because users can drop indexes. 


Archival Logging Selected Files 


Name Type Range Default Units 


Archival Logging Boolean On/Off Off N/A 
Selected Files 


This setting controls whether the MicroKernel performs archival 
logging, which can facilitate your file backup activities. If a system 
failure occurs, you can use the archival log files and the BUTIL - 
ROLLFWD command to recover changes made to a file between the 
time of the last backup and a system failure. 


To direct the MicroKernel to perform archival logging, you must 
specify the files for which the MicroKernel is to perform archival 
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logging by adding entries to an archival log configuration file that 
you create on the volume that contains the files. For more 
information about archival logging, refer to “Understanding 
Archival Logging and Continuous Operations” on page 8-2. 


Initiation Time Limit 


Name Type Range Default Units 
Initiation Time Limit Numeric 1 - 1800000 10000 milliseconds 


This setting specifies the time limit that triggers a system transaction. 
The MicroKernel initiates a system transaction when it reaches the 
Operation Bundle Limit or the time limit, whichever comes first, or 
when it needs to reuse cache. 


Operation Bundle Limit 


Name Type Range Default Units 
Operation Bundle Limit Numeric 1 - 65535 65535 N/A 


This option specifies the maximum number of operations 
(performed on any one file) required to trigger a system transaction. 
The MicroKernel initiates a system transaction when it reaches the 
bundle limit or the Initiation Time Limit, whichever comes first, or 
when it needs to reuse cache. 


The MicroKernel Database Engine treats each user transaction 
(starting with Begin Transaction until End Transaction or Abort 
Transaction) as one operation. For example, if there are 100 Btrieve 
operations between the Begin Transaction and the End Transaction 
operation, then all the 102 Btrieve operations together are treated as 
a single operation. 


Transaction Durability 


Name Type Range Default Units 
Transaction Durability Boolean On/Off On N/A 





Caution Do not turn off Transaction Durability unless your database 
does not require transaction atomicity among data files. Database 
integrity for multi-file databases cannot be guaranteed if Transaction 
Durability is turned off. 
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Do not turn off Transaction Durability unless doing so is supported by 
your application vendor. 





This setting controls whether the MicroKernel performs transaction 
durability by logging all operations that affect the data file. These 
operations are written to a transaction log. Transaction log segments 
are written to the location specified in the setting Transaction Log 
Directory on page 4-19. The log segments are named *.LOG, where 
the prefix can be 00000001 through FFFFFFFF. 


Transaction durability is the assurance that the MicroKernel finishes 
writing to the log before returning a successful status code. This 
option also guarantees multi-file transaction atomicity, which 
ensures that if any given change within the transaction cannot 
complete, then none of the changes are completed. An atomic 
change does not leave partial or ambiguous effects in the database. 
Changes to individual files are atomic whether transaction durability 
is on or off. But transactions make it possible to group changes to 
multiple files into one atomic change. The atomicity of these multi- 
file transactions are assured by the MicroKernel only when using 
Transaction Durability. 


If a system failure occurs after the Transaction log has been written 

but before the “committed” operations are flushed to the data files in 
a system transaction, the “committed” operations are not lost. When 
the database engine starts up again after the system failure, it reads 

the log segments and flushes any “committed” operations to the data 
files. Log segments are deleted only after the operations are flushed 
to the data files. 


This feature allows individual client transactions to receive a 
successful status code as soon as possible while at the same time 
taking advantage of performance gains offered by grouping multiple 
client transactions together and writing them to the data files 
sequentially. 
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~ Note When you turn Transaction Durability on, some files may not be 
able to support the feature. A file must contain at least one unique key 
or have the Compatibility | System Data configuration option set to 
Yes or If Needed. Otherwise, any changes to the file are not written to 
the transaction log. For files that do not contain a unique key, System 
Data creates a unique system-defined log key. For more information 
about transaction durability and system data, refer to Pervasive.SQL 
Programmer's Guide available with the SDK. 


Because System Data does not affect existing files, you may need to re- 
create files that were not created with System Data turned on and do 
not have a unique key. Be sure to turn on System Data before re- 
creating these files. 








x 
Caution Gateway locator files allow different engines to manage files 
in different directories on the same file server. If your database contains 
data files in different directories, you must be sure that the same 
database engine manages all the data files in the database. If you have 
more than one database engine managing files within the same 
database, database integrity and transaction atomicity are not 
guaranteed. For more information on how to avoid this potential 
problem, see “Re-directing Locator Files” on page 9-8. 





Related Settings 


The server configuration settings Performance Tuning | Log Buffer 
Size and Performance tuning | Transaction Log Size are related to 
Transaction Durability. Log Buffer Size allows you to configure the 
balance between transaction recoverability and performance. The 
larger the log buffer, the fewer times it is written to disk, and thus the 
greater the performance. However, database changes that are in the 
log buffer are not durable through a system failure. If you must have 
the absolute maximum level of transaction recoverability, then you 
want to set the log buffer to its smallest value. If you are willing to risk 
some recoverability in favor of even minor gains in performance, 
then you want to set the log buffer larger. 


Transaction Log Size controls how large each log segment gets before 
a new segment is started. Note that all these settings are ignored if 
Btrieve or SQL transactions are not being used. 


Debugging 
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Wait Lock Timeout 


Name Type Range Default Units 
Wait Lock Timeout Numeric 0 - 4294697 15 seconds 


This setting specifies the wait lock timeout for the MicroKernel. 
When you fetch records with a wait lock, the MicroKernel does not 
return control until it has obtained the lock on every record you 
requested. If another application has locked one of the records you 
requested, the MicroKernel waits until that application releases the 
record before proceeding with the lock request. If the wait lock 
timeout has been reached and the MicroKernel could not lock the 
record, the MicroKernel returns control to its caller with the 
appropriate status code. 


The purpose of this option is to significantly reduce network traffic, 
therefore improving network performance in case of a conflict 
caused by locking. With one exception (as stated in the following 
note), this configuration option does not have any effect on your 
application if there is a requester (such as W3BIFxyy.DLL) between 
your application and the MicroKernel. In this case, even if the wait 
lock timeout is reached, the requester retries the operation (except 
for Win16 applications) without notifying your application. The 
control is returned to your code only if the lock has been granted or 
a deadlock has been detected. 





~ Note Ifyou have Win16 applications working with Pervasive.SQL, you 
may want to set this option to a value lower than the default (such as 1 
second). For more information on how the MicroKernel handles wait 
locks with Win16 applications running on Windows 3.x, Windows 95/ 
98, or Windows NT, refer to the Pervasive.SQL Programmer’s Guide. 





Number of Bytes from Data Buffer 


Name Type Range Default Units 


Number of Bytes from Numeric 0 - 65535 128 bytes 
Data Buffer 


This setting specifies the size of the data buffer that the MicroKernel 


writes to the trace file. The Trace Operation feature must be set to On 
to use this feature. The size you specify depends on the nature of your 
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tracing needs (whether you need to see the entire data buffer 
contents or just enough of the buffer contents to identify a record). 


Number of Bytes from Key Buffer 


Name Type Range Default Units 
Number of Bytes from Numeric 0 - 255 128 bytes 
Key Buffer 


This setting specifies the size of the key buffer that the MicroKernel 
writes to the trace file. The Trace Operation feature must be setto On 
to use this feature. The size you specify depends on the nature of your 
tracing needs (whether you need to see the entire key buffer contents 
or just enough of the buffer contents to identify a key). 


Select Operations 


Name Type Range Default Units 
Select Operations Multiselect See below All N/A 


The Selected list displays the available Btrieve Interface operation 
codes that are traced. 


= To remove a Btrieve Interface operation from the Selected list, 
highlight the operation, and click the < button. To remove all of 
the Btrieve Interface operation codes from the Selected list, click 
the << button. The operations will move to the Available list. 


= ‘Toadda Btrieve Interface operation to the Selected list, highlight 
the operation in the Available list, and click the > button. To add 
all of the Btrieve Interface operation codes to the Selected list, 
click the >> button. The operations will move to the Selected 
list. 


@ Abort Transaction (21) @ Get Position (22) 

@ Begin Transaction (19) @ Get Previous (7) 

@ Clear Owner (30) @ Get Previous Extended (37) 
@ Close (1) @ Insert (2) 

+ Create (14) @ Insert Extended (40) 

@ Create Index (31) @ Open (0) 

@ Delete (4) @ Reset (28) 


@ Abort Transaction (21) 
@ Drop Index (32) 

@ End Transaction (20) 
e Extend(16) 

@ Find Percent (45) 

@ Get By Percent (44) 
@ Get Direct/Chunk (23) 
@ Get Directory (18) 

@ Get Equal (5) 

@ Get First (12) 

@ Get Greater (8) 

@ Get Greater or Equal (9) 
+ Get Last (13) 

@ Get Less or Equal (11) 
@ Get Less Than (10) 

@ Get Next (6) 


@ Get Next Extended (36) 


Trace File Location 


Name Type 
Trace File Location String 
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Get Position (22) 

Set Directory (17) 

Set Owner (29) 

Stat (15) 

Step First (33) 

Step Last (34) 

Step Next (24) 

Step Next Extended (38) 
Step Previous 

Stop (25) 

Step Previous Extended (39) 
Unlock (27) 

Update (3) 

Update Chunk (53) 


Version (26) 


Default Units 
C:\pvsw\bin\mkde.tra N/A 


This setting specifies the trace file to which the MicroKernel writes 
trace information. The file name must include a drive or volume 
specification and path or use a UNC path. If you do not want the 
trace file in the default location, enter a different path and/or file 


name. 





— Note Do not use the same trace file name for ODBC tracing and 


MicroKernel tracing. 
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Trace Operation 


Name Type Range Default Units 
Trace Operation Bool On/Off Off N/A 


This setting enables or disables the trace feature, which allows you to 
trace each Btrieve Interface call and save the results to a file. 
Developers can use tracing to debug applications. The MicroKernel 
writes to the trace file using forced write mode, which ensures that 
data gets written to the file even if the MicroKernel unloads 
abnormally. The MicroKernel's performance can be severely 
impacted, depending on the frequency of incoming requests. If you 
enable this option, you must specify a Trace File. 





~ Note You do not need to restart the engine in order to start and stop 
tracing. You can turn tracing on or off during runtime and apply the 
changes directly to the engine. If you receive a message from 
Configuration indicating that you must restart the engine for changes 
to take effect, you may safely ignore the message for this setting. 





DBNames Configuration Location 


Name Type Range Default Units 
DBNames Configuration String N/A Varies N/A 
Location 


This setting specifies the path to an alternate location for the 
DBName configuration file. 


For Server engines, this is a local file path, not a directory path. For 
Workgroup engines this could be a remote path that is accessible to 
the Workgroup MicroKernel. The defaults vary depending upon 
your particular engine platform: 

= Windows NT/2000: C:\WINNT 

= Windows 9X/ME: CAWINDOWS 

m NetWare server: SYS:SYSTEM 

= Unix server: /usr/local/psql/etc 


If you do not want the configuration file in the default location, enter 
a valid path. 


Memory Usage 
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Transaction Log Directory 


Name Type Range Default Units 
Transaction Log String N/A Varies N/A 
Directory 


This setting specifies the location the MicroKernel uses to store the 
transaction log. The path must be a valid path and include a drive or 
volume specification or UNC path. The defaults vary depending 
upon your operating system: 

= Windows: CAPVSWIBINIMKDEILOG 

m NetWare server: SYS:SYSTEM\MKDE\LOG 

= = Unix: /usr/local/psql/log 


Working Directory 


Name Type Range Default Units 
Working Directory String N/A Same directory as N/A 
data file 


This setting specifies the location of the MicroKernel working 
directory, which is used to store temporary files in operations such as 
building large indexes. If disk space is limited on certain volumes, 
you can use this option to specify a working directory on a volume 
with adequate space. 


There is no default value specified; however, if you do not specify a 
working directory, the default will be the location of the data file. To 
specify a fixed working directory, enter a path in the Value text box. 
The path must include a drive or volume specification or a UNC 
path. 


Allocate Resources at Startup (Windows/Unix engines 
only) 


Name Type Range Default Units 
Allocate Resources at Boolean On/Off Off N/A 
Startup 


This setting instructs the MicroKernel to allocate resources, 
including threads and memory buffers, when the MicroKernel is 
started. 
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If you turn this option off, the MicroKernel does not allocate any 
resources until the first operation request. Pervasive.SQL 
components automatically allocate resources as needed. Therefore, 
in most cases you do not need to do so explicitly. 


Back to Minimal State if Inactive (Windows/Unix engines 
only) 


Name Type Range Default Units 
Back to Minimal State if Boolean On/Off On N/A 
Inactive 


This setting causes the MicroKernel to free considerable memory 
and thread resources to the system and return to a minimal state 
when there are no active clients. This is the initial state in which the 
MicroKernel begins. The MicroKernel reallocates resources when 
another client becomes active. 


Extended Operations Buffer Size 


Name Type Range Default Units 


Extended Operations Numeric 0-65536000 Dynamic bytes 
Buffer Size 


This setting is no longer configurable. 


This value specifies the size of the buffer required to handle extended 
(multiple record) operations. 


Minimal State Delay (Windows/Unix engines only) 


Name Type Range Default Units 
Minimal State Delay Numeric 0 - 4294967 30 seconds 


This setting specifies a time interval for the MicroKernel to wait 
before returning to a minimal state. (This is the initial state in which 
the MicroKernel begins.) By returning to a minimal state, the 
MicroKernel frees considerable memory and thread resources to the 
system. In some cases, you may not want the MicroKernel to return 
to a minimal state. For example, you may be running a batch file that 
uses the MicroKernel repeatedly. The MicroKernel reallocates 
resources when another client becomes active. 
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Sort Buffer Size 


Name Type Range Default Units 
Sort Buffer Size Numeric O - limited by memory 0 bytes 


This setting specifies the maximum amount of memory (in 
kilobytes) that the MicroKernel dynamically allocates and de- 
allocates for sorting purposes during run-time creation of indexes. 


If the memory required for sorting exceeds the size specified or is 
greater than 60 percent of the available process memory, the 
MicroKernel creates a temporary file. The amount of available 
memory for a process is a dynamic value and varies according to 
system configuration and load. If you specify 0 kilobytes, the 
MicroKernel allocates as much memory as needed, up to 60 percent 
of the available memory. 


System Cache (Windows/Unix engines only) 


Name Type Range Default Units 
System Cache Boolean On/Off On N/A 


This option specifies whether the MicroKernel should use the system 
cache in addition to the MicroKernel's own database cache, as set 
using the configuration parameter Cache Allocation Size. In most 
cases, performance is enhanced by turning on the System Cache. The 
MicroKernel relies on the system cache to organize and group pages 
to be written. It delays a flush long enough to allow the system cache 
to write the pages to disk in a more efficient manner. However, if 
your server has an advanced self-cached disk array, you might 
achieve better performance by turning System Cache off. 


For Windows Server only: you can use the Paging File and Process 
objects in the Windows NT/2000 Performance Monitor utility to 
determine whether the Windows system cache is being used 
effectively. For the NTDBSMGR instance, monitor the % Usage and 
% Usage Peak in the Page File object and the Page Faults/Second and 
Page File Bytes in the Process object. 
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Cache Allocation Size 


Name Type Range Default Units 


Cache Allocation Size Numeric 65536 - limited Dynamic bytes 
by memory 


By default, this setting is dynamically managed by the database 
engine. Pervasive recommends that you use the default behavior. 


This setting specifies the size of the cache (in bytes) that the 
MicroKernel allocates; the MicroKernel uses this cache when 
accessing any data files. The MicroKernel uses options that are 
multiples of 16 KB. If you specify a number that is not a multiple of 
16 KB, the MicroKernel rounds that number down to the nearest 
multiple of 16 KB and allocates the cache to exactly that size. 


To optimize your performance, allocate a cache size no larger than 
the sum ofthe sizes ofthe files you are using. However, be careful not 
to take all available memory, especially when the server is running 
other applications. You cannot improve performance—and may 
waste memory—by specifying a value higher than you need. 


In Pervasive.SQL 2000i, the MicroKernel dynamically generates a 
default cache size value every time it starts. 


= For Server engines, this value is 20 percent of the physical 
memory on the server platform. 


= For Workstation/Workgroup engines, the default cache size is 
10% of the physical memory or 8 MB, whichever is less. 


This default value is automatically used as the current value for this 
setting the very first time the engine is started after installation. The 
MicroKernel writes this value in the Registry or in BTI.CFG if it does 
not already exist. When the MicroKernel is started in the future, it 
recalculates the default cache size, but it always uses the value that 
was written to the registry. This value appears in Configuration. 


Communications Threads 


Name Type Range Default Units 
Communications Numeric 1- 1024 16 N/A 
Threads 


This setting specifies how many threads the MicroKernel initially 
spawns to handle requests from remote clients. Communication 
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threads are the elements that actually perform Btrieve operations on 
behalf of the requesting remote client process. In this way they are 
very similar to Worker threads. The difference is that 
communications threads are not spawned dynamically. They reside 
in a fixed pool in a sleep state until a request comes in. 


On NetWare, each supported protocol spawns the specified number 
of communications threads. For example, if you set this to 3 threads, 
you will have 3 SPX and 3 TCP/IP threads, making a total of 6 
threads. 


This setting may need to be increased for large servers. Although it 
may be optimal to have one thread for each remote session, this is not 
feasible in most multi-user environments. Use Monitor to watch the 
peak communication thread usage and the peak number of sessions. 
Set the value of Communication Threads in between the two. It does 
not need to be larger than the peak number of sessions because those 
sessions do not all issue a request at exactly the same time. A good 
rule of thumb is to set this to the number of remote clients, up to 
about 32, then use Monitor to determine whether you need to set this 
number any higher. If the peak number of communication threads is 
within two (2) of the maximum, you may want to raise the 
Communications Threads value higher. 


Index Balancing 


Name Type Range Default Units 
Index Balancing Boolean On/Off Off N/A 


This setting controls whether the MicroKernel performs index 
balancing. Index balancing increases performance on read 
operations; however, when you enable this option, the MicroKernel 
requires extra time and may require more disk I/O during insert, 
update, and delete operations. For more information about index 
balancing, refer to Pervasive.SQL Programmer’s Guide available with 
the SDK. 


Largest Compressed Record Size 


Name Type Range Default Units 
Largest Compressed Numeric 0 - 65536000 Dynamic bytes 
Record Size 


This setting is no longer configurable. 
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Log Buffer Size 


Name Type Range Default Units 


Log Buffer Size Numeric 262144 - limited by Dynamic bytes 
memory 


This setting specifies the size of both the transaction log buffer and 
the archival log buffer that the MicroKernel uses. You can enhance 
performance by increasing the log buffer size, because the 
MicroKernel writes the log information to disk less frequently. 





~ Note If you set the Log Buffer Size to a value greater than that of your 
Transaction Log Size, then the MicroKernel automatically increments 
the Transaction Log Size to the value you specified for the Log Buffer 
Size. 





Number of Input/Output Threads 


Name Type Range Default Units 
Number of Input/Output Numeric 1 - 1024 4 N/A 
Threads 


This setting specifies how many background I/O threads the 
MicroKernel spawns. These threads are responsible for writing all 
pages from the MicroKernel’s cache to the file on disk in an atomic 
and consistent manner. They also are responsible for initially 
opening a file and reading the File Control Record. Most of the other 
reads are done by local worker threads and communication threads. 
When the MicroKernel updates or writes to data files, it assigns each 
file to a particular I/O thread sequentially. When it reaches the last 
thread, the MicroKernel starts over until all data files have been 
assigned to a background thread. Because the MicroKernel does not 
spawn additional I/O threads as needed, specify the maximum 
number of I/O threads you anticipate needing. 


For best performance, set this value based on the average number of 
Open Files. Monitor shows the current and peak number of files 
open. If your database has an average of 100 files open, then the 
default of 4 I/O threads makes each thread responsible for 25 files. A 
good rule of thumb is to have about 8 files per I/O thread. For 
example, if your average number of open files is 100, you should use 
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about 12 I/O threads. Specifying a value higher than 64 may degrade 
performance, but that depends on the capabilities of the system. 





Note Application Developers: There is no accurate way to calculate the 
appropriate number of I/O threads because this setting depends on the 
machine’s characteristics, OS configuration, and the MicroKernel 
Database Engine’s planned work load. 





Number of Worker Threads (Windows/Unix server 
engines only) 


Name Type Range Default Units 
Number of Worker Numeric 1 - 1024 1 N/A 
Threads 


Worker threads are the elements that actually perform Btrieve 
operations on behalf of the requesting local client process. This 
setting specifies how many worker threads the MicroKernel initially 
spawns to handle requests from local clients. 


In general, there is little reason to adjust this setting because the 
MicroKernel spawns additional threads as needed. 


Transaction Log Size 


Name Type Range Default Units 
Transaction Log Size Numeric 65536 - limited 524288 bytes 
by disk space 


This setting specifies the maximum size ofa transaction log segment. 
When the log file reaches its size limit, the MicroKernel closes the old 
log segment file and starts anew one. You might want to limit the size 
of your transaction log segments, because this reduces the disk space 
that the MicroKernel uses temporarily. However, limiting the size of 
the transaction log segments does require more processing by the 
MicroKernel and can decrease performance, because it has to close 
and create log segments more frequently. 
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~ Note If you set the value for this option less than the value you 
specified for the Log Buffer Size, the MicroKernel Database Engine 
automatically adjusts the Transaction Log Size by setting it to the value 
of the Log Buffer Size option. 





Runtime Server Support 


Name Type Range Default Units 
Runtime Server Support SelectOne See below Complete N/A 


This setting specifies the level of Runtime Server Support provided 
by the MicroKernel. The available options are Complete, Disabled, 
or Pre-Authorized. 


= Specify Complete when you want to require the user to provide 
a valid user name; you can also specify a password, although not 
required. 


= Specify Pre-Authorized when you want to require the user to 
enter a valid user name and password. 


= Specify Disabled when you want the user to only have a 
connection to the NetWare server to access any Btrieve files. If 
the user is not connected to the server, s/he will receive a Status 
Code 99, “The Btrieve Requester is unable to access the NetWare 
Runtime server.” 


SUPERVISOR and ADMIN are not valid user names, even if 
supplied with the correct password. If the Requester cannot find a 
login user name other than SUPERVISOR or ADMIN, there is no 
valid name to pass. For more information about Runtime Server 
Support, see your Novell documentation. 


Configuration 
Mapping 


Server Configuration Parameters 


The following table is a mapping of all the available Server 
configuration options and their settings. It shows where the settings 
can be found in both the default and Component views (if available). 


Table 4-2 Server Configuration Mapping 





























Default View 
Parameter Setting Name Component View Component View 
Category Parameter 
Access Accept Remote Btrieve Server 
Request! Communications Communication 
Manager Configuration 
Authentication? 
Configuration File? 
Load brouter? 
Number of Btrieve Server 
Sessions Communications Communication 
Manager Configuration 
Communica- | Brouter 
tion Buffer Communication 
Size Buffer Size? 
Communication MicroKernel Trace Btrieve 
Buffer Size Database Engine Operations 
MKDE MicroKernel Memory Resources 
Communication Database Engine 
Buffer Size 





Read Buffer Size? 


Btrieve 
Communications 
Manager 


Server 
Communication 
Configuration 








Receive Packet 
Size? 
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Table 4-2 Server Configuration Mapping 


























Default View 
Parameter Setting Name Component View Component View 
Category Parameter 
Communica- | Listen IP Address 
tion Protocol 
NetBIOS Port? 
ODBC Connection 
Mgr Supported 
Protocol? 
Supported Btrieve Server 
Protocols Communications Communication 
Manager Configuration 
TCP/IP Multinomed 
TCP/IP Port? 
Use SAP? 
Compatibility | Create File Version | MicroKernel File Settings 
Database Engine 
System Data MicroKernel File Settings 


Data Integrity 


Archival Logging 
Selected Files 


Initiation Time Limit 
Operation Bundle 
Limit 


Transaction 
Durability 


Database Engine 


MicroKernel 
Database Engine 


MicroKernel 
Database Engine 


MicroKernel 
Database Engine 


MicroKernel 
Database Engine 


Files Settings 
Client/System 
Transactions 


Client/System 
Transactions 


Client/System 
Transactions 








Wait Lock Timeout 





MicroKernel 
Database Engine 





System Resources/ 
Directory 
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Default View 
Parameter Setting Name Component View Component View 
Category Parameter 
Debugging Number of Bytes MicroKernel System Resources/ 
from Data Buffer Database Engine Directory 
Number of Bytes MicroKernel Trace Btrieve 
from Key Buffer Database Engine Operations 
Select Operations MicroKernel Trace Btrieve 
Database Engine Operations 
Trace File Location | MicroKernel Trace Btrieve 
Database Engine Operations 
Trace Operation MicroKernel Trace Btrieve 
Database Engine Operations 
Directories DBNames 
Configuration 
Location 
Transaction Log MicroKernel System Resources/ 
Directory Database Engine Directory 
Working Directory MicroKernel System Resources/ 
Database Engine Directory 
Memory Allocate Resource | MicroKernel System Resources/ 
Usage at Startup! Database Engine Directory 








Back to Minimal 
State if Inactive! 


MicroKernel 
Database Engine 


System Resources/ 
Directory 





Minimal State of 
Delay! 


MicroKernel 
Database Engine 


System Resources/ 
Directory 





Sort Buffer Size 


MicroKernel 
Database Engine 


Memory Resources 








System Cache * 





MicroKernel 
Database Engine 





System Resources/ 
Directory 


4-29 





Configuration Reference 


4-30 


Table 4-2 Server Configuration Mapping 
































Default View 
Parameter Setting Name Component View Component View 
Category Parameter 
Performance | Cache Allocation MicroKernel Memory Resources 
Tuning Size Database Engine 
Communications Btrieve Server 
Threads Communications Communication 
Manager Configuration 
Index Balancing MicroKernel File Settings 
Database Engine 
Log Buffer Size MicroKernel Client/System 
Database Engine Transactions 
Number of Input/ MicroKernel System Resources/ 
Output Threads Database Engine Directory 
Number of Worker 
Threads! 
Transaction Log MicroKernel Client/System 
Size Database Engine Transactions 
NetWare Runtime Server 
RTSS Support? 





1 Windows and Unix engines only. 
2 Unix engines only. 





3 NetWare engines only. 
4 Server engines only. 











Win32 Client Configuration Parameters 





Win32 Client Configuration Parameters 


Access 


The client configuration options are available in all the different 
installation setups. These options must be configured separately for 
each workstation, which includes servers acting as workstations. 


Gateway Durability 


Name Type Range Default Units 
Gateway Durability Boolean On/Off Off N/A 


This option specifies whether the MicroKernel Router should store 
in the registry a list of computers that do not have Pervasive.SQL 
running on them. This decreases the time it takes to find a gateway 
engine. You must set this option to Off when new engines are added 
to the workgroup. 


Number of Load Retries 


Name Type Range Default Units 
Number of Load Retries Numeric 0 - 65536 5 N/A 


This setting specifies the number of times the MicroKernel Router 
attempts to connect to the target engine. 


Target Engine 


Name Type Range Default Units 
Target Engine SelectOne See below On Win9x: Workstation N/A 


On Win NT/2000: Try 
Server, then Workstation 


This setting applies only to the client running on a Windows NT/ 
2000 server where a database engine is installed. This setting is 
ignored on Windows 9X/ME. If you are running on Windows9X/ 
ME, setting this value to “Server” is not permitted. 


If you have both a Workstation engine and a Server engine installed 
on the Windows server, you can use this setting to shorten the initial 
connection time for the engine that you use the most. If you use the 
Server engine most often, you can set it to Try Server, then 
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Workstation so that the client always tries to connect to the local 
Server engine first. 


If you have only a Workstation/Workgroup engine installed, setting 
this parameter to Workstation avoids the wait that occurs when the 
client tries to open a named pipe to a non-existent local Server 
engine. 


If the client occasionally access both a remote Server engine as well 
as the local Server engine, you can use this setting to determine 
which engine the client connects to. In this scenario, the remote 
Server engine is referred to as the Workstation. 


If the setting Use Local MicroKernel Engine is turned Off, then this 
setting is ignored. 


Use IDS 
Name Type Range Default Units 
Use IDS Boolean On/Off On N/A 


This setting specifies that the MicroKernel Router allows access to a 
Pervasive.SQL I*net Data server running on a remote server. Make 
sure this setting is set to On before using any of the IDS configuration 
options. 


Use Local MicroKernel Engine 


Name Type Range Default Units 
Use Local MicroKernel Boolean On/Off On N/A 


This setting determines whether a local application tries to connect 
to a local engine. If set to Off, no attempt is made to connect to a local 
engine. 


Use Remote MicroKernel Engine 


Name Type Range Default Units 
Use Remote MicroKernel Boolean On/Off On N/A 


This setting specifies whether the MicroKernel Router allows access 
to a Server or Workgroup engine running on a remote server. If this 
value is set to On, and Use Local MicroKernel is set to On, the remote 
server is tried first. 


Communica- 
tion Protocols 


Win32 Client Configuration Parameters 


Prior to Service Pack 3, this setting was named “Requester.” 





"Note We recommend you keep Use Remote MicroKernel Engine set 
to On for a Microsoft's File and Print Services for NetWare (FPNW) 
server running Pervasive.SQL. You may receive a Status Code 94, “The 
application encounter a permission error,” if you change this setting to 
Off when you are running the Btrieve Interface locally on the FPNW 
server and using a local FPNW drive mapping or local FPNW UNC 
path. 





Enable Auto Reconnect 


Name Type Range Default Units 
Enable Auto Reconnect Boolean On/Off Off N/A 


This setting specifies whether you want the client to attempt to auto- 
reconnect during a network outage. A setting of “On” means 
AutoReconnect is enabled. 


Auto Reconnect is not in effect unless this setting is also enabled in 
the server configuration. 


Supported Protocols 


Name Type Range Default Units 
Supported Protocols Multiselect N/A Varies N/A 


This setting specifies the protocols that are used by the 
Communications Requester. If more than one protocol is specified, 
the Communications Requester attempts to connect using all 
available protocols. When the first protocol succeeds, that protocol is 
used for the remainder of the session. The default value varies 
depending upon the platform; the available options are: 


Table 4-3 Client Supported Protocols 


@ Microsoft TCP/IP @ Novell SPX 
@ Microsoft SPXII @ Microsoft NETBIOS 
+ IBM NETBIOS + 
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~~ Note You must have at least one specific protocol that is enabled at 
both the client and the server, or else they cannot communicate. 





TCP/IP Timeout for Communication Requester 


Name Type Range Default Units 


TCP/IP Timeout for Numeric 1 - 2147483647 15 seconds 
Communication Requester 


This setting specifies the number of seconds the requester should 
wait for any connection request to succeed before timing out. 





Note Despite the name for this setting, this setting applies to all 
protocols, not just TCP/IP. 





Compress IDS Data 


Name Type Range Default Units 
Compress IDS Data Boolean On/Off Off N/A 


This setting determines if the MicroKernel Router uses compression 
with the IDS server. Using compression may allow the data to be 
transmitted in fewer TCP/IP packets and may improve performance. 


IDS Password 


Name Type Range Default Units 
IDS Password String N/A None N/A 


This is the password used by the MicroKernel Router to log into a 
Pervasive.SQL I*net Data Server running on a remote server. There 
is no default value and a password must be set by the system 
administrator on the I*net Data Server and the Use IDS 
configuration option must be set to On before using this option. 


Win32 Client Configuration Parameters 


IDS Username 


Name Type Range Default Units 
IDS Username String N/A None N/A 


This is the name used by the MicroKernel Router to log into a 
Pervasive.SQL I*net Data Server running on a remote server. There 
is no default value and a user name must be set by the system 
administrator on the I*net Data Server and the Use IDS 
configuration option must be set to On before using this option. 


Runtime Server Support 


Name Type Range Default Units 
Runtime Server String Yes Yes N/A 
Support No 


user_name:password 


This setting controls runtime server support. If enabled with the 
value Yes, the current user name and password for the drive on which 
you are presently running are used. To enable RTSS with a different 
username, enter “user_name:password”. 





Note SUPERVISOR and ADMIN are not valid user names, even if 
supplied with the correct password. If the requester cannot find a login 
user name other than SUPERVISOR or ADMIN, it does not attempt to 





login. 
Application Embedded Spaces 
Characteristics Name Type Range Default Units 
Embedded Spaces Boolean On/Off Off N/A 


This option instructs the Btrieve Interface to allow embedded spaces 
in filenames for Btrieve operations. 
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Splash Screen 


Name 


Splash Screen 


Type 
Boolean 


Range 
On/Off 


Default 


Units 
N/A 


This setting controls whether or not the Btrieve Interface splash 
screen displays. The splash screen displays the first time a Btrieve 
requester is loaded. 





Note The 32-bit Configuration utility enables/disables the splash 


screen for 32-bit applications and 16-bit applications when thunking is 


set to On. For 16-bit applications, if thunking is set to Off, use the 
Client-16-bit Application characteristics options to disable the splash 


screen. 





The following table is a mapping of all the available Client 
configuration options and their settings. It shows where all the 
settings can be found in both the default and Component views (if 


available). 


Table 4-4 Client Configuration Settings 



































Default View 
Category Parameter Name Component Component View 
View Category Parameter 
Access Gateway Durability | MicroKernel Access Control 
Router 
Number of Load MicroKernel Access Control 
Retries Router 
Target Engine MicroKernel Access Control 
Router 
Use IDS MicroKernel Access Control 
Router 
Use Local MicroKernel Access Control 
MicroKernel Router 
Use Remote MicroKernel Access Control 
MicroKernel Router 
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Table 4-4 Client Configuration Settings 









































Default View 
Category Parameter Name Component Component View 
View Category Parameter 
Communication | Enable Communications | Access Control 
Protocols AutoReconnect Requester 
Supported Communications | Access Control 
Protocols Requester 
TCP/IP Timeout for | Communications | Access Control 
Communication Requester 
Requester 
Performance Compress IDS Data | MicroKernel Access Control 
Tuning Router 
Security IDS Password MicroKernel Access Control 
Router 
IDS Username MicroKernel Access Control 
Router 
Runtime Server Communications | Access Control 
Support Requester 
Application Splash Screen Btrieve Client Configuration 
Characteristics Requester 
Embedded Spaces | MicroKernel Access Control 
Router 
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This section describes the configuration options available for the 16- 
bit client. These must be changed at each individual client and will 
be used only when running legacy applications. There is no 
relational engine access when using 16-bit client applications. 


Use Local MicroKernel Engine 


Name Type Range Default Units 
Use Local Microkernel Boolean On/Off On N/A 
Engine 


This setting determines whether a local application tries to connect 
to a local engine. If set to Off, no attempt is made to connect to a local 
engine. 


Use Remote MicroKernel Engine 


Name Type Range Default Units 
Use Remote MicroKernel Boolean On/Off On N/A 
Engine 


This setting specifies whether the MicroKernel Router allows access 
to a MicroKernel server engine running on a remote server. If this 
value is set to On, and Use Local MicroKernel is set to On, the remote 
server is tried first. 


Splash Screen 


Name Type Range Default Units 
Splash screen Boolean On/Off On N/A 


This setting controls whether or not the Btrieve Interface splash 
screen displays. The splash screen displays the first time a Btrieve 
requester is loaded. 


Communica- 
tion Protocols 


Win16 Client Configuration Parameters 


Use IDS 
Name Type Range Default Units 
Use IDS Boolean On/Off On N/A 


This setting specifies that the MicroKernel Router allows access to a 
Pervasive.SQL I*net Data server running on a remote server. Make 
sure this setting is set to On before using any of the IDS configuration 
options. 


Use Thunk 
Name Type Range Default Units 
Use Thunk Boolean On/Off On N/A 


This setting specifies whether the Win16 client requester uses 
thunking to access Win32 components. This option must be turned 
on when on a Win32 platform (Windows NT/9X/2000) accessing 
Win16 (Btrieve) applications. 


Supported Protocols 


Name Type Range Default Units 
Supported Protocols Multiselect N/A Varies N/A 


This setting specifies the protocols that are used by the 
Communications Requester. If more than one protocol is specified, 
the Communications Requester will attempt to use TCP/IP first. If 
TCP/IP is not available, it uses SPXII. In the case of Unix servers, the 
only protocol that can be used is TCP/IP; SPX is will not function. 
The default value varies depending upon the platform; the available 
options are: 


Table 4-5 Client 16-bit Supported Protocols 
@ Microsoft SPX @ Microsoft NETBIOS 


@ Microsoft TCP/IP @ NWIPX/SPX SPX 
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TCP/IP Timeout for Communication Requester 


Range Default Units 


1 - 2147483647 15 


Name 


TCP/IP Timeout for 
Communication Requester 


Type 


Numeric seconds 


This setting specifies the number of seconds the requester should 
wait for a TCP/IP connect request to succeed before timing out. 


Runtime Server Support 


Name Type Default Units 


Runtime Server String Yes Yes N/A 
Support No 
user_name:password 


Range 


This setting controls runtime server support. If enabled with the 
value Yes, the current user name and password for the drive on which 
you are presently running are used. To enable RTSS with a different 
username, enter “user_name:password”. 





Note SUPERVISOR and ADMIN are not valid user names, even if 
supplied with the correct password. If the requester cannot find a login 
user name other than SUPERVISOR or ADMIN, it does not attempt to 
login. 


The following table is a mapping of all the available 16-bit Client 
configuration options and their settings. It shows where all the 
settings can be found in both the default and Component views (if 
available). 


Table 4-6 16-bit Client Configuration Settings 
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Default View 

Parameter Setting Name Component View Component View 
Category Parameter 

Access Use Local MicroKernel Router | Access Control 





MicroKernel Engine 





Use Remote 
MicroKernel Engine 








MicroKernel Router 





Access Control 
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Table 4-6 16-bit Client Configuration Settings 

















Default View 
Parameter Setting Name Component View Component View 
Category Parameter 
Application Splash Screen Btrieve Requester Client Configuration 
Characteristics 
Use IDS MicroKernel Router | Access Control 
Use Thunk MicroKernel Router | Access Control 
Communication | Supported Communications Access Control 
Protocol Protocols Requester 





TCP/IP Timeout for 
Communication 
Requester 


Communications 
Requester 


Access Control 








Security 








Runtime Server 
Support 





MicroKernel Router 





Access Control 
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An Exploration of Object Names, Named Databases, and DSNs 


This chapter delves into Named Databases and DSNs. It is divided 
into the following sections: 

= “Identifiers and Object Names” on page 5-2 

= “DSN Creation Options” on page 5-5 

= “Connection Strings” on page 5-9 


m “Maintain Named Databases” on page 5-12 
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Identifiers and Object Names 


Regular and 
Delimited 


Maximum 
Length 


An identifier is the name of a column, table, procedure, cursor, or 
other named object within the database. A regular identifier is an 
identifier that is not surrounded by double quotes. A delimited 
identifier is an identifier surrounded by double quotes. 


A regular identifier must begin with a letter, either upper or lower 
case. The remainder of the identifier can consist of any combination 
of upper or lower case letters, digits, and the underscore character 
(“_”). You cannot use a reserved word as a regular identifier. Regular 
identifiers are case-insensitive, so that the identifiers Abc, ABC, and 
abc are identical and can be used interchangeably. 


A delimited identifier can consist of any string enclosed in double 
quotes. While it is not recommended, reserved words can be used as 
delimited identifiers. For example, INSERT is not permitted as a 
regular identifier, but "INSERT" is permitted as a delimited 
identifier. If you need to represent a double-quote within a delimited 
identifier, use a pair of double quotes without a space between them. 


Almost all identifiers are limited in length. For delimited identifiers, 
the size limit includes the opening and closing quotations. 


Table 5-1 Maximum Length of Identifiers 





























Type of Identifier Maximum number of characters 
allowed 

Table 20 

View 20 
Column 20 
Index 20 
Foreign key 20 
User/group name 30 
Password 8 
Database 20 
Stored procedure 30 











Examples 


Unique Scope 


Identifiers and Object Names 


Table 5-1 Maximum Length of Identifiers continued 




















Type of Identifier Maximum number of characters 
allowed 

Trigger 30 

Variable none 

Data file path name 64 (the maximum length of the 
data file path name is a 
combination of Xf$Loc path and 
the data file path) 








The following identifiers are permitted: 


"INSERT" 

myInsert 

"my Insert" 

"3tableA" 

Table56 

"Table 56 & (*#)" 

Long table name 1234 [20 characters] 

"Long table name123" [20 characters including quotes] 





The following identifiers are not permitted: 


INSERT [reserved word requires quotes] 

my Insert [spaces require quotes] 

3tableA [regular identifier must start with a letter] 

Table56 (*#) [regular identifier contains only alpha-numeric characters] 
Long table name 12345 [21 characters] 

"Long table name1234" [21 characters including quotes] 


Identifiers generally must be unique within a certain scope. That is, 
instances of the same type of object using the same name cannot be 
used within the same arena. Table 5-2 shows the arena, or the scope, 
within which a given object name must be unique. 


Table 5-2 Unique Scope for Common Identifiers 





A name for this type of object ... ... must be unique within this scope: 





Database All databases hosted by a given 
database engine 











Table Database 
Trigger or stored procedure Database 
User or group Database 
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Table 5-2 Unique Scope for Common Identifiers 




















A name for this type of object ... ... must be unique within this scope: 
Cursor Database 

View Database 

Constraint Database 

Column Table 

Index Table 
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DSN Creation Options 


Engine DSN 
Open Mode Op- 
tions 


This section explains in detail the driver options that can be 
configured for Pervasive.SQL DSNs. 


The DSN Open Mode options available for Engine DSNs allow you 
to specify one of several characteristics that go into effect when tables 
are opened through the specified DSN. These options are mutually 
exclusive —you are not permitted to select more than one. 


These options correspond directly to the Btrieve open modes 
allowed in the Open (0) operation. By setting an Open Mode for a 
DSN, you are setting the default behavior for tables (corresponding 
to Btrieve files) opened through that DSN. 


Table 5-3 DSN Open Modes and ODBC Connection Options 





This Open Mode ... | ... generates this ODBC | ... and this 
connection string ... SQLSetConnectOption call: 
Normal OPENMODE=0 SQLSetConnectOption( 
pSubDbc, 


SQL_ACCESS_MODE, 
SQL_MODE_READ_WRITE); 








Accelerated OPENMODE=-1 SQLSetConnectOption is 
ignored 

Read-only OPENMODE=1 SQLSetConnectOption( 
pSubDbc, 


SQL_ACCESS_MODE, 
SQL_MODE_READ_ONLY); 





Exclusive OPENMODE=-4 SQLSetConnectOption is 
ignored 














Normal 


Normal mode is the default. Opening a table in Normal mode allows 
read/write access according to the permissions defined in the 
database. 


If this mode is selected, the ODBC connection string includes 
OPENMODE-O, and the following ODBC function call is executed 
when you connect to the database: 


SQLSetConnectOption(pSubDbc, SQL ACCESS MODE, 
SOL MODE_READ WRITE); 
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Accelerated 


Opening a table in Accelerated mode provides increased insert/ 
update performance by disabling database engine logging functions 
for the current user. Logging is not affected for other users accessing 
the same table. 


x4 





Caution Because no logging occurs for the given user when this mode 
is in effect, the database engine cannot guarantee transaction 
atomicity, transaction durability, or archival log safety during use of 
Accelerated mode. 


For example, if a system failure occurs while the same file is being 
accessed by a client performing inserts using Accelerated mode and a 
client performing updates using Normal mode, it is possible for the 
transaction log to contain updates to records that do not yet exist in the 
data files, because the Accelerated insert operation in memory was 
never flushed to disk, while the transactional update operation was 
written to the transaction log. 


When this mode is selected, the ODBC connection string includes 
OPENMODE=-1, and the SQLSetConnectOption call is ignored by 
the ODBC driver. You cannot use SQLSetConnectOption to specify 
this mode. 


Read-only 


When a table is opened in read-only mode, operations that modify 
the database structure or the data in the database are not permitted. 


If this mode is selected, the ODBC connection string includes 
OPENMODF=1, and the following ODBC function call is executed 
when you connect to the database: 


SQLSetConnectOption(pSubDbc, SQL ACCESS MODE, 
SQL MODE READ ONLY); 


Exclusive 


When a table is opened in exclusive mode, no other connections to 
the table are permitted. If other users are currently accessing the 
given table, it cannot be opened in Exclusive mode. You must try 
again later. 


Client DSN Op- 
tions 


DSN Creation Options 


When this mode is selected, the ODBC connection string includes 
OPENMODE=-4, and the SQLSetConnectOption call is ignored by 
the ODBC driver. You cannot use SQLSetConnectOption to specify 
this mode. 


In the Pervasive Client DSN Setup window, the following options 
can be modified if you click Options. 


Enable Array Fetch 


An array fetch is a memory cache on the client machine for result 
sets. When array fetch is enabled, data from the latest result set is 
cached to the client machine's local memory, thereby speeding 
performance on subsequent queries. We recommend you leave array 
fetch “On,” if you will be doing multiple queries. 


The default size of the buffer used to cache array fetches is 8KB. You 
can set it anywhere between 1 and 64KB. 


TCP/IP Port Number 


You can use this setting to change the network port number on 
which Pervasive.SQL transmits ODBC communications. The 
network layer on the server engine has a similar setting, described in 
“TCP/IP Port (Server engines only)” on page 4-10. You must change 
both settings at the same time, and you must change them both to 
the same port number, or else your client and server cannot 
communicate. 


x; 





Caution Do not change the client port number unless you also change 
the corresponding port number on the server. If the server and client 
are not using the same port number, they cannot communicate. 





Generally, the only reason you would need to change this port 
number is if you have another network service that is already using 
this port, and it is easier to change the port number for your 
Pervasive.SQL applications than for the other application. 


The Btrieve interface communicates over port 3351. This value is not 
configurable. 
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Use OEM/ANSI Conversion 


This setting allows applications to store or retrieve character data in 
any OEM character set using Pervasive.SQL, while allowing the data 
to be manipulated and displayed using the ANSI Windows character 
set. The Pervasive ODBC driver translation DLL can perform all 
necessary translations between the two character sets. This feature 
can be turned on or off for each DSN. 


The Pervasive Control Center (PCC) and the SQL Data Manager 
(SQLDM) are not fully OEM-character aware if you use extended 
ASCII characters for column or table names. However, any character 
data that is passed to and from the database is correctly translated 
between the OEM and ANSI character sets. OEM-character-aware 
column and table names within PCC and SQLDM will be fully 
enabled in a future service pack. 


If your application connects to the data source using 
SQLDriverConnect, you can also specify the translation DLL using 
the connection string option 
TRANSLATIONDLL=path_and_DLL_name. The translation DLL 
name for Pervasive.SQL is W32BTXLT.DLL. 


NOTE: The OEM to ANSI translation option is available only for 
client or local Engine DSNs. It is not available when setting up a 
remote Engine DSN. 


Connection Strings 





Connection Strings 


This section describes the ODBC connection strings supported by 
Pervasive.SQL. This information is provided for two audiences: 


= advanced users using a database access tool that allows 
connection strings to be specified (such as ODBC Test) 

= developers writing ODBC, ASP, or OLE DB applications to 
access Pervasive.SQL. 


Users of Pervasive.SQL 7 should note that the connection string 
parameters have changed significantly between Pervasive.SQL 7 and 
Pervasive.SQL 2000. 


Driver Name 


If you wish to connect to a database engine that is running on the 
same computer as the program that is attempting to connect, use the 
following driver connection string: 


Driver={Pervasive ODBC Engine Interface} 


If you wish to connect to a remote database engine using the 
Pervasive.SQL client, use the following driver connection string: 


Driver={Pervasive ODBC Client Interface} 


Other Parameters 


The tables below shows the other parameters that may be used. 
Engine connection strings may be used for both connections to a 
local database engine and to a remote engine. Client connection 
strings may only be used for connections to a remote Server engine. 


Table 5-4 Engine Connection Strings 





Connection String Description 





DBQ=[ @ ]db_name Specify the internal database name (not DSN) to which 
you wish to connect. Required. 


The @ character is optional. It has no particular effect 
and is supported only for backward compatibility. 





UlD=user_name If security is enabled for the given database, specify the 
user name. Optional, depending on security. 
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Table 5-4 Engine Connection Strings 


Connection String 





Description 





PWD=password 


If security is enabled for the given database, specify the 
password. Optional, depending on security. 





OPENMODE=-41-11011 


Specify the default file open mode for files opened with 
the current connection. Default is 0, “Normal.”Can be 
used only with local connections, not remote client 
connections. Optional. 


For more information on file open modes, see “Engine 
DSN Open Mode Options” on page 5-5. 





TRANSLATIONDLL= 
path_and_DLL_name 








Specify the full path name of the DLL to use for OEM/ 
ANSI translation. For more information, see “Use OEM/ 
ANSI Conversion” on page 5-8. 





Table 5-5 Client Connection Strings 





Connection String 


ServerName=server[.port] 


Description 


Specify the machine name or IP address of the 
computer to which you wish to connect. If you are not 
using the default port, specify the port number to use. 
Required. 





ServerDSN=dsn_name 


Specify the Engine DSN to which you wish to connect. 
Required, unless DBQ is specified. 





TransportHint= 
<TCPISPX>[:SPXITCP] 


Specify the transport protocol to use, or which to try 
first. Default is TCP:SPX. Optional. 


For example, a value of “TCP” forces the client to try a 
TCP/IP connection only. A value of “SPX:TCP” forces 
the client to try an SPX connection first, and if that fails, 
to try a TCP/IP connection. 





TCPPort=port 


Specify the TCP/IP port on which to find the server. 
Default is 1583. Optional. 





ArrayFetchOn=110 


Specify whether to cache result sets on the client. 
Default is 1, “On.” Optional. 





ArrayBufferSize=size 








Examples 


Example A 


Specify the size of the client cache, in KB. Default is 8 
KB. Optional. 











Connection Strings 


This example shows how to connect to a database with the internal 
name “SOMEDATA” on a remote server named “ServerMain” using 
TCP/IP port 1590, trying TCP/IP first then SPX: 


Driver={Pervasive ODBC Client Interface); 
ServerName=ServerMain.1590;DBQO=SOMEDATA; 
TransportHint=TCP:SPX; 


Example B 


This example shows how to connect to an Engine DSN named 
“mydata” on a remote server named “MyServer” with database 
security turned on: 


Driver={Pervasive ODBC Client Interface); 
ServerName=MyServer ; ServerDSN=mydata;UID=ajones; 
PWD=jones52; 


Example C 


This example shows how to connect to a local database with the 
internal name “DATA5”: 


Driver={Pervasive ODBC Engine Interface };DBQ=DATA5; 


See Also 


For further information on Engine DSN open modes, see “Engine 
DSN Open Mode Options” on page 5-5. 


For further information on Client connection string options, see 
“Client DSN Options” on page 5-7. 
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A named database is a database that has a logical name that allows 
users to identify it without knowing its actual location. 
Pervasive.SQL 2000 requires that all databases be named. When you 
name a database, you associate that name with a particular 
dictionary directory path and one or more data file paths. Database 
names are typically used internally by Pervasive.SQL 20001 and most 
users will refer to the database by ODBC Data Source Name (DSN) 
that points to it. 


For ODBC access you must set up a DSN to point to the database 
name. Multiple DSNs may point to the same named database. 


To create, modify or delete database names, the Pervasive.SQL 2000 
Control Center provides a wizard that can be started by right- 
clicking on a machine's Configuration namespace node and 
selecting Maintain named database. The following wizard appears: 


Figure 5-1 Maintain Named Database Wizard Dialog Box 
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Creating a New > 


Bound Data- 
base 


Maintain Named Databases 


Table describes the elements in the Maintain named databases 
dialog box. 


Table 5-6 Maintain Named Databases Dialog Box Elements 


Element 





Description 





Registered DB Names 


Lists available named databases. 





Current database name 


Displays currently selected database name. 





Dictionary Location 


Displays the location of the Data Dictionary Files 
(DDF) for the selected database name. 





Data File Location 


Displays the locations of data files for the database. 





Bound 


Indicates whether or not the database is bound. 
Binding a database ensures that the MicroKernel 
enforces the database defined security, referential 
integrity (RI), and triggers, regardless of the method 
used to access the data. 


For more information about bound databases, refer to 
the API Programmer's Reference. 








1 


Integrity Enforced 





Displays whether integrity constraints (security, RI, 
and triggers) are being enforced on the database. 








To create a bound database 


Right-click on the Configuration namespace node of the 
machine on which the named database is to be created. 


Open the Maintain Named Databases from the pop-up menu. 


The Maintain Named Databases dialog box appears. 
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Figure 5-2 Maintain Named Databases Dialog Box 
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3 Click on the Add database icon in the upper left hand corner of 


the dialog box. A new named database will appear in the 
Registered DB Names panel with its name highlighted. Type in 
a name for the new database, making sure not to use any spaces. 


Specify the location for the database in the Dictionary Location 

field. This location must be on the same server to which you are 

connected. 

+ For NetWare, enter a path in the form vol: Y path. 

+ For Windows NT, enter a path in the form drive : \ path, where 
drive is the local drive letter. 

+ For Unix, enter the standard Unix path format from root. 

Specify the location of the data file(s) in the Data File Locations 


field. Click on the Add File Location icon just above the 
directory list or click on the next available blank line in the list. 


If you are specifying paths to data file(s) on this server, specify 
them in the same manner as in the Dictionary Location field. If 
you are entering paths to data files on another server, specify the 
full UNC path. 
+ For NetWare, enter the path in the form \\server\vol: \path 
+ For Windows NT, enter the path in the form 
\ \server \sharename \ path 
+ For Unix, enter the path in one of two ways: 
\\server\share\ path or 
\\server\ $PVSWS \ path 


Maintain Named Databases 


You can select a data file path in the list and press the Delete file 
location icon if you decide not to include a specific data file 
location. 


Select Bound to bind this database, if desired. 


7 Select Integrity enforced to enforce integrity constraints 
(security, referential integrity, and triggers) on this database, if 
desired. 


8 Select Create DDF Files, if desired. 
Click Apply. 


Figure 5-3 Create Named Database Dialog Box 
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Modifying Named Databases 


» To modify a named database 

1 Click on the database name in the Registered DB Names list. 
2 Add or modify the named database attributes. 

3 Click Apply. 


4 Add or modify data file locations. 
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Deleting Named Databases 


» To delete a named database 
1 Click on the database name in the Registered DB Names list. 


2 Click on the Delete database icon. You can also right-click on the 
database name and select Delete from the pop-up menu. 





Note Deleting a Named Database without deleting the corresponding 
DSN(s) results in “orphaned” DSNs. Because the underlying database 
has been removed, these DSNs do not work. You should always remove 
any DSNs created for a Named Database if you delete the Named 
Database. 
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An Introduction to Referential Integrity Structures 


Referential Integrity is a system of checks and balances that you can 
create in your database to ensure that tables with related data remain 
synchronized. 

= “Concepts of Referential Integrity” on page 6-2 

m “Setting up Primary Keys” on page 6-6 

m “Setting up Foreign Keys” on page 6-8 
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Concepts of Referential Integrity 


Definitions 
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Referential Integrity (RI) allows you to modify or prohibit updates, 
inserts, or deletes based on whether identical field values exist in the 
same or other tables. 


A good understanding of RI depends upon a clear understanding of 
several important terms: 


Rule 


A rule is a simple statement of cause and effect, carried out by the RI 
system defined in the database. 


Example A 


For example, a delete rule defines what happens to records containing 
a foreign key when a record containing a primary key is deleted: 
“When the record containing ‘Bhargava Building’ is deleted, all rows 
in Table A that reference that record are deleted.” 


A delete rule can also prohibit the row containing the primary key 
value from being deleted if there are any foreign key values that 
reference the given primary key value. 


Example B 


An update rule defines what happens to a record containing a foreign 
key when a user attempts to update the record or add a new record: 
“When a user attempts to insert a new record to Table B, reject the 
attempt if the building name does not exist in Table C.” 


Primary key 


A primary key is the column or columns upon which a rule depends. 
Only one primary key is permitted in any table, and the primary key 
must not allow duplicate values. For an update rule, the primary key 
is the column or columns against which updated or inserted 
columns are compared to determine if the updated or inserted 
record should be allowed. 


In Example A above, the column containing “Bhargava Building” is 
the primary key. 


Concepts of Referential Integrity 


In Example B above, the column in Table C that contains the 
building name is the primary key. 


Foreign key 


A foreign key is the column or columns that are compared against a 
primary key to determine how to proceed. 


In Example A above, the column in Table A that may contain the 
value “Bhargava Building” is the foreign key. 


In Example B above, the column in Table B that contains the building 
name is the foreign key. 


Cascade 


A cascade rule is a rule in which the database permits the desired 
operation to occur, then enforces RI by changing other tables or rows 
to synchronize with the first operation. 


For example, if a delete cascade rule is defined, deleting a record in the 
primary key table causes the database to find and delete all rows 
throughout the database that have foreign key values the same as the 
primary key value of the deleted row. 


Restrict 


A restrict rule is a rule in which the database decides whether or not 
to permit the desired operation based on existing values in the 
database. 


for example, if an update restrict rule is defined, an attempt to add a 
row to a table containing a foreign key causes the database engine to 
compare the value in the foreign key field to the values in the primary 
key. Ifthere is no primary key row with the same value, the new row 
is not permitted to be added to the foreign key table. 


Understanding This section explores the concepts behind primary keys and foreign 
Keys and Rules keys in further detail. 
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Figure 6-1 Primary and Foreign Keys 


























Table A Table B 
@student_ID Name @stud_ID e Class 
20543 John 20543 ENG-101 
20577 Mary 20543 AST-202 


























In the example shown in Figure 6-1, the column named student_ID 
in Table A (A. student_1D) is an IDENTITY data type that does not 
allow two rows to the have the same value. Every student has a 
unique ID number. We will define student_IDas the primary key of 
Table A. 


We can then define the column named stud_1p in Table B 
(B.stud_ID) as a foreign key that references A. student_ID. Note 
that the data type of stud_ID must be a type that can be compared 
with IDENTITY, such as INTEGER. The data types of primary and 
foreign keys must be compatible. You can have as many foreign keys 
as you need in order to enforce your desired referential integrity 
scheme. Multiple foreign keys can reference the same primary key. 


The table with the primary key can be referred to as the parent table, 
while the table with the foreign key is called the child table. Once the 
keys are defined, we have a range of behaviors to choose from. 


Table 6-1 Choices for RI Rules 





If you want this behavior ... ... define this rule: 





Do not allow a row to be inserted or updated in Table B | Update Restrict 
unless the proposed value of B.stud_ID matches any 
value in A.student_ID. 





Do not allow a row to be deleted from Table A if any Delete Restrict 
value of B.stud_ID matches that row. 





If a row is deleted from Table A, delete all rows from Delete Cascade 
Table B in which B.stud_ID matches the value of 
A.student_ID in the deleted row. 














Update Restrict 


Continuing with the example, setting an update restrict rule ensures 
that the value of B. stud_ID in any new or updated row must first 


Concepts of Referential Integrity 


exist in A. student _ID. It follows, then, that you must have rows in 
Table A before you can add any rows in Table B. Stated another way, 
you must create at least one parent row before you can create a child 
row. 


Delete Restrict 


In the example, setting a delete restrict rule ensures that a row from 
Table A cannot be deleted if any rows in Table B reference that row. 
You cannot delete the row with Name value “John” because John’s 
student ID is referenced in Table B. 


Once all rows from Table B that reference John’s student ID are 
deleted, then John's row can be deleted from Table A. 


Delete Cascade 


In the example, setting a delete cascade rule ensures that both records 
in Table B are deleted if the row with Name value “John” is deleted. 
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Setting up Primary Keys 


Creating a Pri- 
mary Key Dur- 
ing Table 
Creation 


Adding a Pri- 
mary Key to an 
Existing Table 
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You must create primary keys using SQL statements. Pervasive 
Control Center does not provide this ability in the user interface, 
unless you wish to modify by hand the SQL statement created by 
Create Table Wizard before you generate the table. 


You can create a primary key when you create a table, by using the 
PRIMARY KEY keywords in your CREATE TABLE statement. A 
primary key can consist of one or more columns. The example below 
shows the column named id being created then being designated the 
primary key: 

CREATE TABLE mytable (id INTEGER, 


myname CHAR(20), 
PRIMARY KEY (id) ) 


The example below shows how to create a primary key using more 
than one column as the unique key value: 


CREATE TABLE mytable (id INTEGER, 
myname CHAR(20), 
PRIMARY KEY(id, myname) ) 


If you do not specify the UNIQUE attribute on the column or 
columns that you designate as a primary key, the database engine 
automatically creates an index on the designated columns that does 


not allow duplicate values or null values in the columns. Null values 
are never allowed in a key column. 


For more examples, see CREATE TABLE in SQL Engine Reference. 


You can add a primary key to an existing table, by using the ALTER 
TABLE statement with ADD PRIMARY KEY key words. You must 
create the primary key on a column or columns that do not allow 
duplicate values or null values. 


If necessary, you can modify the column attributes and make the 
column the primary key at the same time: 


ALTER TABLE mytable MODIFY id INTEGER UNIQUE NOT NULL 
PRIMARY KEY 


If you want to add a primary key consisting of more than one 
column, you must add the key separately: 


ALTER TABLE ADD PRIMARY KEY(id, myname) 


Setting up Primary Keys 


For more examples, see ALTER TABLE in SQL Engine Reference. 
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Setting up Foreign Keys 


Creating a For- 
eign Key During 
Table Creation 


Adding a For- 
eign Key to an 
Existing Table 
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You must create foreign keys using SQL statements. Pervasive 
Control Center does not provide this ability in the user interface. 


When you create a foreign key, you must define the associated rule at 
the same time. You can define multiple rules on the same key. 


You can create a foreign key when you create a table, by using the 
REFERENCES keyword in your column definition. A foreign key can 
consist of one or more columns. The data types of the column(s) 
must be the same as the primary key that this foreign key references. 
The example below shows the column named your_id being created 
then being designated the foreign key, referencing mytable. id: 


CREATE TABLE yourtable (your_id INTEGER REFERENCES 
mytable(id) ON DELETE CASCADE, yourname CHAR (20) ) 








You can also add the foreign key designation at the end of the 
statement. You must use this technique if you wish to use multiple 
columns in the key: 


CREATE TABLE yourtable (your_id INTEGER, 
yourname CHAR(20), 
FOREIGN KEY(your_id, yourname) REFERENCES 
mytable(id, myname) ON DELETE CASCADE) 


When you create a foreign key, the database engine adds an index on 
the designated columns. 


For more examples, see CREATE TABLE in SQL Engine Reference. 


You can add a foreign key to an existing table, by using the ALTER 
TABLE statement with ADD FOREIGN KEY key words. In the 
example below, two rules are defined for this foreign key, both a 
delete rule and an update rule: 


ALTER TABLE yourtable ADD FOREIGN KEY (your_id, yourname) 
REFERENCES mytable(id,myname) ON DELETE CASCADE ON 
UPDATE RESTRICT 


For more examples, see ALTER TABLE in SQL Engine Reference. 
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How to Work with Btrieve Owner Names and Relational Security 


Pervasive.SQL provides support for Btrieve owner names as well as a 
full implementation of relational database security. This chapter 
explains the relationship between the two, and how to work with 
both. 


If you are looking for information about securing the database 
engine and/or administrative access to the database engine, see 
Chapter 2 of Pervasive.SQL User’s Guide. 

= “Owner Names” on page 7-2 

m “Relational Security” on page 7-4 

= “Owner Names and Relational Security” on page 7-6 


= “Data Encryption” on page 7-7 
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Owner Names 


For information on how to 

set or clear an owner name, 
pene . 

see “Setting or Clearing an 

Owner Name” on page 13- 

20 


For information about how 
owner names interact with 
relational security, see 
“Owner Names and 
Relational Security” on page 
7-6. 
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An owner name is a password required to gain access to a Btrieve file. 
There is no relation between an owner name and any system user 
name or database user name. You should think of an owner name as 
a simple file password. 


You can use Maintenance Utility to set or clear an owner name ona 
file. An owner name can have several attributes, as shown in Table 
7-1. 





























Table 7-1 Owner Name Options 
Option Description 
Read-only Without specifying the password, users can perform data 
access operations that do not modify the data file. 
Read-only Without specifying the password, users can perform data 
encrypted access operations that do not modify the data file. When you 
set this option, the database engine encrypts every record in 
the file using the owner name as a key. Records added later 
are also encrypted. 
Normal Without specifying the password, users cannot perform any 
file access operations. 
Normal Without specifying the password, users cannot perform any 
encrypted file access operations. Any records inserted or updated are 
encrypted using the password. When you set this option, the 
database engine encrypts every record in the file using the 
owner name as a key. Records added later are also encrypted. 
Remarks 


When you first set an owner name with encryption on a file, the 
database engine encrypts the entire file. The larger the file is, the 
longer this procedure takes. 


Data access operations to an encrypted file are slower than to a 
normal file. The database engine must decrypt each page as it reads 
it from disk, and encrypt it again before writing it back to disk. 


y ` 





Caution Do not forget or lose a file's owner name, especially with 
encryption turned on. There is no way to find out the owner name, and 
no way to get access to the data without it. 





Owner Names 


If you attempt to access a file that has an owner name declared 
without supplying the owner name, you receive the message, “You 
are not authorized to perform the operation.” 
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Relational Security 


Securing a Da- 
tabase 


For information about how 
Btrieve owner names 
interact with relational 
security, see “Owner Names 
and Relational Security” on 
page 7-6. 


Setting up Us- 
ers and Groups 


This section explains the basic concepts of Pervasive.SQL security. 


A database can be secured in one of two ways: 


= In Pervasive Control Center (PCC), right-click on the database, 
select Properties, then click on the Security tab. Enter and 
confirm the password for the Master user in the boxes provided. 
When you click OK or Apply, security is enabled. For detailed 
instructions on this procedure, see Pervasive.SQL User’s Guide. 


=» From an ODBC application connected to the database, issue the 
SQL statement SET SECURITY= ‘password’ where password is 
the text string you want to use as the password for the Master 
user. For more information on SET SECURITY, refer to SQL 
Engine Reference. 


When turning security on or off, the Master user must have only one 
connection open and must be the only user connected. 


As soon as you turn security on for the first time, only the Master 
user can access the database. The Master user password, as with all 
Pervasive.SQL passwords, is case sensitive. 





~ Note You cannot use SQL Data Manager in PCC to issue a SET 
SECURITY statement. Attempting to do so generates an error because 
both SQL Data Manager and PCC keep an open connection to the 
database. 





Relational security is based on the existence of a default user named 
“Master” who has full access to the database when security is first 
turned on. Initially, no password is required for the Master user. 





& 
Caution If you turn on security, be sure to specify a password with a 
significant length, at least five characters. Do not leave the password 
field blank because doing so creates a major security risk for your 
database. 





The Master user can create groups and other users and define sets of 
data access privileges for these groups and users. 


Relational Security 


If you want to grant the same level of access to all users and avoid 
having to set up individual groups and users, you can grant the 
desired level of access to PUBLIC. The default user PUBLIC 
represents any user connecting with or without a password. 





~ Note If you wish to use groups, you must set up the groups before 
creating users. You cannot add a user to a group after you have already 
created the user. 





You can use the Users node in PCC to perform these tasks. You can 
also use GRANT and REVOKE statements in SQL to perform these 
tasks. Keep in mind that passwords are case sensitive. 


See Pervasive.SQL User's Guide for information on performing these 
tasks within PCC. 


Restrictions 
A given user cannot be a member of more than one group. 


All users in a group have exactly the permissions defined for that 
group. You cannot grant or revoke individual permissions for a user 
who is a member of a group. 


Assigning a user to a group overrides and erases any individual 
permissions that were granted to the user beforehand. 


You cannot add an existing user to a group. To do so, you must delete 
the user and re-create the user as a member of the group. 


You cannot add a group to another group. 
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Owner Names and Relational Security 


If you have a Btrieve owner name set on a file that is a table in a secure 
ODBC database, the Master user of the ODBC database must use the 
owner name in any GRANT statement to grant privileges on the 
given table to any user, including the Master user. 


After the GRANT statement containing the owner name has been 
issued for a given user, that user can access the specified table by 
logging into the database, without specifying the owner name each 
time. 


If a user tries to access a table through ODBC that has a Btrieve 
owner name, the access will not be allowed unless the Master user has 
granted privileges on the table to the user, with the correct owner 
name in the GRANT statement. 


If a table has an owner name with the Read-Only attribute, the 
Master user automatically has SELECT rights on this table without 
specifically granting himself/herself the SELECT rights with the 
owner name. 


Examples 


To grant himself/herself full access to a table with an owner name, 
the Master user must enter the following SQL statement: 


GRANT ALL ON table-name owner-name TO Master 


To grant SELECT rights on a table named mytable with an owner 
name of jim56, the Master user must enter the following SQL 
statement: 


GRANT SELECT ON mytable jim56 to bob_smith 


Data Encryption 





Data Encryption 


Pervasive.SQL offers encryption of data files on disk. To require that 
your data files be encrypted when written to disk, you must set an 
owner name on each file. 


See “Owner Names” on page 7-2 for more information. 
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Understanding and Using the Backup Features of Pervasive.SQL 


Pervasive.SQL 20001 provides two powerful features to support 
online backups and disaster recovery. 


= “Understanding Archival Logging and Continuous Operations” 
on page 8-2 
= “Using Archival Logging” on page 8-4 


=» “Using Continuous Operations” on page 8-14 
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Understanding Archival Logging and Continuous 


Operations 


Archival Log- 
ging and Trans- 
action 
Durability 
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The product offers two mutually exclusive features to support online 
backups and disaster recovery. 


If your situation is like this ... ... use this feature: 





You must keep your database applications running Continuous operations 
while performing backups. 





You are able to shut down the database engine to Archival logging 
perform backups 














Archival Logging allows you to keep a log of all database operations 

since your last backup. In case of a system failure, you can restore the 
data files from backup then roll forward the changes from the log file 
to return the system to the state it was in prior to the system failure. 


Continuous Operations allows you to backup database files while the 
database engine is running and users are connected. After starting 
Continuous Operations, the database engine closes the active data 
files and stores all changes in temporary data files (called delta files). 
While Continuous Operations are in effect, you perform a backup of 
the data files. The delta files record any changes made to the data files 
while the backup is taking place. When the backup is complete, you 
turn off Continuous Operations. The database engine then reads the 
delta file and applies all the changes to the original data files. The 
temporary delta file may surpass the size of the original data file if 
users make extensive changes to the file during continuous 
operation. 





~ Note You cannot turn on Continuous Operations if Archival Logging 
is in operation. Likewise, you cannot turn on Archival Logging if 
Continuous Operations are in effect. These two features are mutually 
exclusive and cannot be used at the same time. 





Transaction Durability is another feature designed to protect the 
integrity of your data in the event of a system failure. Transaction 
Durability is not directly related to Archival Logging. You can have 
Transaction Durability in effect at the same time as either Archival 


What if a File 
Restore is 
Needed 


Understanding Archival Logging and Continuous Operations 


Logging or Continuous Operations. Transaction Durability uses a 
short-term log file to ensure that transactions are written to disk 
before a successful status code is returned. The transaction log is 
reset frequently as completed client transactions are rolled into the 
physical data files by way of system transactions. In the event of a 
system failure, when the database engine starts up again, it reads the 
transaction log and flushes to disk the transactions that were 
completed prior to the system failure. 


The archival log is written to at the conclusion of each system 
transaction, so the archival log and the transaction log should 
remain properly synchronized unless a system failure occurs exactly 
during the system transaction. 


For more information on Transaction Durability, see “Transaction 
Durability” on page 4-12. 


In the event of a system crash that requires restoring data files from 
backup, Archival Logging allows you to restore from backup and 
then recover database activity up to the moment of the crash. 


If you experience a similar crash without Archival Logging (for 
example if you use Continuous Operations to perform backups), 
then you will not be able to recover database activity that took place 
between the last backup and the system crash. 


Table 8-1 Data Restore Limits After Crash 








If Archival Logging is ... ... this much data will be unrecoverable after 
a crash: 

On Unfinished transactions at the moment of 
failure. 

Off All database operations that have occurred 
after the last backup of the data files. 











The remainder of this chapter describes the options and procedures 
associated with Archival Logging and Continuous Operations. 
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Using Archival Logging 


General Proce- 
dures 
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This section explains the procedures you must follow to set up 
Archival Logging, make backups, and restore data files. 


For Archival Logging to work properly, you must follow a clearly 
defined procedure to set it up, and another procedure in the event 
that a restore from backup is necessary. 


y 





Caution If any steps of the procedures are omitted or compromised, 
you may not be able to restore your data to its pre-crash state. 





> To use Archival Logging properly 


1 Turn on Archival Logging, if it is not already in effect. See 
“Setting up Archival Logging” on page 8-5 for the detailed set- 
up procedure. 


2 Shut down the database engine. 
3 Backup the data files. 


4 After a successful backup, delete all existing archival logs. 





z 
Caution Delete the corresponding log files before you resume working 
with the data files. Synchronizing the backup data files and the 
corresponding log files is a critical factor of successful recovery. 





5 Restart the database engine. 


» To restore data files from backup and apply changes 
from the archival log 





~~ Note You cannot use this procedure to roll forward the archival log if 
you experienced a hard disk crash and your archival log and data files 
were both located on the lost hard disk. 





1 When the computer re-starts after the system failure, ensure that 
the database engine is not running, and ensure no other database 
engine is accessing the data files you wish to restore. 


Setting up Ar- 
chival Logging 


2 
3 


y 


4 


5 
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Restore the data files from backup. 


Start the database engine, ensuring that no applications of any 
kind are connected to the engine. 





Caution Itis crucial that no database access occurs before the archival 
log has been applied to the data files. Make sure no other database 
engine accesses the files. You must roll forward the archival log using 
the same engine that encountered the system failure. 





Issue the Roll Forward command as described in “Roll Forward 
Command” on page 8-8. 


After the Roll Forward completes successfully, stop the database 
engine and make a new backup of the data files. 


After you have successfully backed up the data files, delete the 
archival log files. You may now re-start the database engine and 
allow applications to access the data files. 


Setting up Archival Logging requires two steps: 


ma. 


turning on the Archival Logging feature 


specifying the files to archive 





Note To perform these procedures, you must have administrative 
permissions or be a member of the Pervasive_Admin group on the 
computer where the target database engine is running. 





To turn on Archival Logging 


Start up PCC. Click Start and choose Programs | Pervasive | 
Pervasive.SQL 20001 | Pervasive Control Center. 


Double-click Pervasive.SQL 20001 Engines. Double-click the 
engine icon representing the target database engine. 


If you don't see the engine you want to work with, see 
Pervasive.SQL User's Guide for information on how to register a 
remote server engine. 


Double-click Configuration. Double-click Server. Click Data 
Integrity. 
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4 Right-click Archival Logging Selected Files. From the pop-up 


5 


menu, click Properties. In the dialog box that appears, click On. 


Click OK. 


> To specify files to archive 


You specify the files for which you want the MicroKernel to perform 
Archival Logging by adding entries to an archival log configuration 
file you create on the volume that contains the files. To set up the 
configuration file, follow these steps: 


1 


Create the directory \BLOG in a real root directory of the 
physical drive that contains data files you want to log. (That is, 
do not use a mapped root directory.) If your files are on multiple 
volumes, create a \BLOG directory on each volume. 


For example, if you have data files located on C:\ and D:\, and 
both drives are physical drives located on the same computer as 
the database engine, then you would create two BLOG 
directories, as below: 

C:\BLOG\ 

D:\BLOG 

In each \BLOG directory, create an empty BLOG.CFG file. You 


can use any text editor, such as NotePad, to create the 
BLOG.CFG file. 


In each BLOG.CFG file, create entries for the data files on that 
drive for which you want to perform Archival Logging. Use the 
following format to create each entry: 


\ path1\ dataFile [ =\ path2\ logFile] 


path! The path to the data file to be logged. The path cannot 
include a drive letter. 


dataFile The name of the data file to be logged. 

path2 The path to the log file. Because the log file and the data 
file can be on different drives, the path can include a drive 
letter. 

logFile The name of the log file. If you do not specify a name, the 


default value is the same directory and file name prefix as 
the data file, but replace the file name suffix with “.log”. 
You may specify a different physical drive, so that the log 
and the data files are not on the same drive. 
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A single entry cannot contain spaces and must fit completely on 
one line. Each line can contain up to 256 characters. If you have 
room, you can place multiple entries on the same line. Entries 
must be separated by white space. You must terminate the end of 
the line with a Return character. 


If you do not provide a name for the log file, the MicroKernel 
assigns the original file name plus a LOG extension to the log file 
when you first open it. For example, for the file B.BTR, the 
MicroKernel assigns the name B.LOG to the log file. 


y 





Caution You are not required to log every file in your database. 
However, if your database has referential integrity (RI) rules defined, 
you must log all or none of the files involved in each RI relationship. If 
you log only a sub-set of the files involved in a given RI relationship, 
rolling the archival log forward after a system crash may result in 
violations of your RI rules. 





Examples 


The following examples show three sample entries in the BLOG.CFG 
file on drive C. All three entries produce the same result: activity in 
the file C:\DATA\B.BTI is logged to the file C:\DATA\B.LOG. 


\data\b.bti 

\data\b.bti=\data\b.log 

\data\b.bti=c:\data\b.log 
The next example directs the engine to log activity in the file 
C:\DATA\B.BTI to the log file D:\DATA\B.LGF. This example shows 
that archival log files do not have to reside on the same drive as the 
data file and do not require a .LOG extension. (The .LOG extension 
is the default.) 

\data\b.bti=d:\data\b.lgf 


v a 
Z 





Tip Writing the log to a different physical drive on the same computer 
is recommended. If you experience a hard disk crash, having the log file 
on a different physical disk protects you from losing your log file and 
your data file at the same time. 
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The Btrieve Maintenance utility (GUI or BUTIL command line) 
provides a command allowing you to roll forward archival log files 
into the data files. The BUTIL -ROLLFWD command recovers 
changes made to a data file between the time of the last backup and 
a system failure. Ifa system failure occurs, you can restore the backup 
copy of your data file and then use the BUTIL -ROLLFWD 
command, which applies all changes stored in the archival log to 
your restored data files. Do not use this command unless you have 
restored data files from backup. 





Note You cannot take advantage of the ROLLFWD command unless 
you both enable the MicroKernel's Archival Logging Selected Files 
option and back up your files before a system failure occurs. 





You can also use the ROLLFWD command to produce an output file 
of logged operations. The ROLLFWD command can produce the 
output file either before you roll changes forward or at the same time 
as the roll forward. 


You can roll forward a single file, all data files on a volume, all data 
files on a drive, or a list of files, volumes, and/or drives. 
Using the GUI 


1 From the Start menu, choose Programs | Pervasive | 
Pervasive.SQL 20001 | Utilities | Maintenance. 


2 Within the Maintenance window, choose Data | Roll Forward... 
The Roll Forward dialog box (Figure 8-1) appears. 


Only Create Dump File 
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Figure 8-1 Roll Forward Dialog 


E Roll Forward Lx] 





r Select File(s) to Roll Forward 
Operation Type Single File; example: c:\data\class.mkd 


Single File y] A] Browse | 











-Dump File Options 
TF Generate Dump File 

[> Only Greate Dump File (do not Roll Forward) 
Dump File Name; example: SELUGSERULILLST, 


\BLOG\BROLL.LST 


Data Butter F Display Numbers as HEX 


[= Verbose 


Key B uffern 











p |] 
pd 
toca | to 








Select the specific operation type: single file, list of files, volume 
name, or drive letter. When you select either volume name or 
drive letter, you must insert a back slash (1) or forward slash (/) 


at the end (for example, \\server\vol1\ or D:\). 


You can generate a log file, called a dump file, of all the Btrieve 


operations required to perform the roll forward tasks. 


By default, this file is not created. Select the Generate Dump File 
check box to generate a file. You can also specify the following 


options. 


Table 8-2 Roll Forward GUI Options 


and the roll forward operation is not to be 
performed. 





Indicates that only the dump file is to be created, 





Dump File Name 


Contains the name of the dump file, which must 
begin with a slash and not contain a drive letter or 
server/volume name. 





Data Buffer Length 


Indicates the number of data buffer bytes to write to 
the dump file for each Btrieve operation. 





Key Buffer Length 


Indicates the number of key buffer bytes to write to 
the dump file for each Btrieve operation. 
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Table 8-2 Roll Forward GUI Options 





Display Numbers as HEX If you select this option, the numbers in the dump 
file output are formatted as hexadecimal. If you do 
not select this check box, the numbers are 
displayed in ASCII format. 





Verbose Includes additional information like user name, 
network address, and time stamp in the dump file. 








Note If the key buffer or the data buffer is not an input parameter for 
the particular Btrieve operation, nothing is written to the dump file. 





5 Click Execute to generate the dump file and/or perform the roll 
forward operation. If the data is valid, the Roll Forward Status 
dialog box (Figure 8-2) appears. 


Figure 8-2 Roll Forward Status Dialog 


E Roll Forward Status Lx] 










Bury File Name 


110  c:ipyswtkdemodataiclass.mkd 





Cancel ] 
Help | 


As files are processed, they are added to the scrolling list box 
which displays the file name and the Pervasive.SQL status code 
returned from the roll forward operation. 


If an error occurs during processing, the Roll Forward Continue 
on Error dialog box appears. This dialog box allows you to 
continue without being prompted again, to continue and be 
prompted again, or to stop processing files. 
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Figure 8-3 Roll Forward Continue on Error Dialog 


Roll Forward Error EH 
File Name: c:/data/room_mkd 


Btrieve Status: 20-MKDE or Requester not loaded 


A Roll Forward Error has occured. Do you want to continue on to 
the next file? 


© Continue; Do not ask again 
© Continue; Ask again 


© Stop Roll Forward operations 








Using the Command Line 


This section explains the syntax for the command line usage of Roll 


Forward. 


BUTIL -ROLLFWD <sourceFile | volume | drive | @listFile> 
[</L[dumpFile] | /W[dumpFile] > [/T<dataLength>] 
[/E<keyLength>] [/H] [/V] [/O<ownerList | owner>|*]] 


[/A] [/S] 


sourceFile 


volume 


drive 


listFile 


/LdumpFile 


/Wdump File 


The fully qualified name of a data file for which to roll forward 
changes. For Windows NT, you do not need to specify the name 
of the path if the data file resides in the same directory as your 
current directory. 


A volume for which to roll forward changes. End the volume 
name with a backslash or forward slash, as in SYS: \, // 
SERVER/SYS/, or \\SERVER\SYS: \. 


A drive letter for which to roll forward changes. End the volume 
name with a backslash (Y or forward slash (/), asin F: \ or F: /. 


The fully qualified name of a text file containing the paths of 
files, volumes, or drives for which to roll forward changes. 
Separate these paths with a carriage return/line feed. If the 
Maintenance utility encounters an error, the utility stops rolling 
forward the current file, but does not roll back the changes 
already made. If you specify the /A option, the utility continues 
rolling forward with the next file. 


Produces an output file, but does not roll forward. 


Rolls forward and produces an output file. 
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dumpFile 


/TdataLength 


/EkeyLength 


/H 


/V 


/O 


/A 


/S (NetWare 
only) 
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The file name of the output file to which the Maintenance utility 
writes a list of logged operations. The default is 
\BLOG\BROLL.LST, relative to the root of the physical drive. 
The file name cannot contain a drive letter or volume name and 
must start with a forward slash (/) or backslash (\). The 
Maintenance utility places the file on the same volume as the 
BLOG.CFG file. 


Specifies the length of the operation’s data buffer to write to the 
output file. If you do not specify this option, the utility does not 
include data buffer contents in the output file. 


Specifies the length of the operation’s key buffer to write to the 
output file. If you do not specify this option, the utility does not 
include key buffer contents in the output file. 


Instructs the utility to show numbers in the output file in 
hexadecimal notation. If you do not specify this option, numbers 
in the output file are in ASCII format. This option affects the 
format of the Entry Count, Op Code, Key Number, and Data 
Length fields. 


Instructs the utility to include additional information (such as the 
user name, network address, and time stamp) in the output file. 


Specifies the owner name of the data file, if required. An owner 
name is required if you request an output file of logged 
operations and the backup copy of the data file has an owner 
name for read-only access. 


If more than one file has an owner name, the respective owner 
names must be separated by commas. See “Owner Names” on 
page 13-37 for more information. 


Specifies that if you are rolling back more than one file and the 
Maintenance utility encounters an error, the utility continues 
rolling forward with the next file. 


When you do not specify this option, the utility stops rolling 
forward if it encounters an error. The utility does not roll back the 
changes already made. 


Note: When you use the /A option, you might want to redirect 
output to a file, as described in “Redirecting Error Messages” 
on page 13-37 and “Command Files” on page 13-35. 


By default, the Maintenance utility stops at each full screen of 
output and waits for a keystroke before continuing. With the /S 
option, the utility continuously scrolls output on the screen. You 
cannot use /S on the command line if you specify a command 
file, but you can specify /S with a command inside a command 
file. 
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— Note If the key buffer or the data buffer is not an input parameter for 
the particular Btrieve operation, nothing is written to the dump file. 





Examples 


Example A The following example recovers changes to the 
CLASS.MKD file from the default archival log and log location. 


butil -rollfwd sys:\pvsw\demodata\class.mkd 


Example B This example recovers changes and outputs them to all 
files on the sys: volume with the following options: 

= use default dump file 

= dump 32 bytes of the data buffer 

= dump 4 bytes of the key buffer 

= dump in hex mode 

butil -rollfwd sys:\ /W /H /T32 /E4 

Example C The following example does not perform roll forward but 
only outputs the changes to the files listed in files.txt with the 
following dump options: 

m use sys:\temp\files.Ist as the dump file 

m use verbose mode 

= data files have owner names: own123 and own321 

= donot dump data or key buffer 


butil -rollfwd @sys:\temp\files.txt /L\temp\files.1lst / 
V /Oown123,own321 
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Continuous Operations provides the ability to backup data files 
while database applications are running and users are connected. 
However, if you use Continuous Operations to make backups, you 
cannot use Archival Logging and the Maintenance utility Roll 
Forward command to restore changes to your data files that occurred 
after the last backup. 


Pervasive.SQL provides two backup commands for Continuous 
Operations: BUTIL and SQLUTIL. The commands are similar. 
SQLUTIL supports data source names (DSNs) as a parameter; 
BUTIL requires file paths. In addition, SQLUTIL runs only on 
Windows-based platforms and NetWare. 


This section provides detailed information on the commands: 


STARTBU and ENDBU. 


Table 8-3 Commands to Start and Stop Continuous Operation 








Command Description 
STARTBU Starts continuous operation on files defined for backup 
(BUTIL). 


Starts continuous operation on data source names defined 
for backup (SQLUTIL). 





ENDBU Ends continuous operation on data files defined for backup. 
(BUTIL). 

Ends continuous operation on data source names defined 
for backup (SQLUTIL). 

















Note The temporary delta files created by Continuous Operations 
mode have the same name as the corresponding data files but use a 
¿AMA extension instead. Therefore, do not create multiple data files 
with the same names but different extensions. For example, do not use 
a naming scheme such as INVOICE.HDR and INVOICE.DET for your 
data files. 





Continuous operation mode does not significantly affect 
MicroKernel performance; however, using a server to back up files 
can affect performance. 


Backing Up a 
Database with 
BUTIL 
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> To protect against data loss using Continuous 
Operation 


1 Use the -STARTBU command to put your files in continuous 
operation. See “STARTBU” on page 8-15 for an explanation of 
the command syntax with BUTIL and on page 8-18 for an 
explanation with SQLUTIL. 


2 Back up your data files. 


3 Use the -ENDBU command to take your files out of continuous 
operation. See “ENDBU” on page 8-17 for an explanation of the 
command syntax with BUTIL and on page 8-20 for an 
explanation with SQLUTIL. 


This section provides detailed information on backing up a database 
using the following BUTIL commands: STARTBU and ENDBU. 


STARTBU 


The BUTIL -STARTBU command places a file or set of files into 
continuous operation for backup purposes. 


Format 


BUTIL -STARTBU <sourceFile | @listFile> [/S] 


sourceFile The fully qualified name of the data file (including the drive 
specification for Windows NT/2000 and volume specification 
for NetWare) on which to begin continuous operation for 
backup. 
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listFile The name of a text file containing the fully qualified names of 
files on which to begin continuous operation. Separate these 
file names with a carriage return/line feed. (Although the 
utility accepts a blank space separator as well, future 
versions of Pervasive.SQL may accept blank characters in 
file names. For compatibility with future versions of 
Pervasive.SQL, use the carriage return/line feed separator.) 


If the Maintenance utility cannot put all of the specified files 
in continuous operation, the utility does not put any of the 
files in continuous operation. 


/S (NetWare only) By default, the Maintenance utility stops at each full screen 
of output and waits for a keystroke before continuing. With 
the /S option, the utility continuously scrolls output on the 
screen. You cannot use /S on the command line if you 
specify a command file, but you can specify /S with a 
command inside a command file. 





Note This command begins continuous operation only on the files 
you specify. You cannot use wildcard characters with the STARTBU 
command. 





Examples for Windows Server 


Example A The first example starts continuous operation on the 
COURSE.MKD file. 


For Windows Server: 
butil -startbu f£:\pvsw\demodata\course.mkd 


Example B The following example starts continuous operation on all 
files listed in the STARTLST.FIL file. 


butil -startbu @startlst.fil 
The STARTLST.FIL file might consist of the following entries: 


£:\pvsw\demodata\course.mkd 
£:\pvsw\demodata\tuition.mkd 
£:\pvsw\demodata\dept .mkd 


Examples for NetWare Server 


Example A The first example starts continuous operation on the 
COURSE.MKD file. 


butil -startbu sys: \pvsw\demodata\course.mkd 
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Example B The following example starts continuous operation on all 
files listed in the STARTLST.FIL file. 


butil -startbu @sys:\test\startlst.fil 
The STARTLST.FIL file might consist of the following entries: 


sys: \pvsw\demodata\course.mkd 
sys: \pvsw\demodata\tuition.mkd 
sys: \pvsw\demodata\dept .mkd 


ENDBU 


The ENDBU command ends continuous operation on a data file or 
set of data files previously defined for backup. Issue this command 

after using the STARTBU command to begin continuous operation 
and after performing your backup. 


Format 


BUTIL -ENDBU </A | sourceFile | @listFile> [/S] 


/A Ifyou specify /A, the utility stops continuous operation on all 
data files initialized by BUTIL -STARTBU and currently 
running in continuous operation mode. 


sourceFile The fully qualified name of the data file (including the drive 
specification for Windows NT/2000 and volume specification 
for NetWare) for which to end continuous operation. 


@listFile The name of a text file containing a list of data files for which 
to end continuous operation. The text file must contain the 
fully qualified file name for each data file, and you must 
separate these file names with a carriage return/line feed. 
(Although the utility accepts a blank space separator as well, 
future versions of Pervasive.SQL may accept blank 
characters in file names. For compatibility with future 
versions of Pervasive.SQL, use the carriage return/line feed 
separator.) 


Typically, this list of data files is the same as the list used with 
the STARTBU command. 


/S (NetWare only) By default, the Maintenance utility stops at each full screen 
of output and waits for a keystroke before continuing. With 
the /S option, the utility continuously scrolls output on the 
screen. You cannot use /S on the command line if you specify 
a command file, but you can specify /S with a command 
inside a command file. 
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Example for Windows Server 


The following example ends continuous operation on the 
COURSE.MKD file. 


butil -endbu f£:\pvsw\demodata\course.mkd 


However, you can also just enter but il -endbu course.mkd instead 
of the full path if your current directory is £ : \demodata. 


Example for NetWare Server 


The following example ends continuous operation on the 
COURSE.MKD file. 


butil -endbu sys: \pvsw\demodata\course.mkd 


SQLUTIL is a command-line utility that runs only on Windows- 
based platforms and NetWare. You can execute SQLUTIL commands 
from the command line or through a command file. SQLUTIL works 
locally on the Pervasive.SQL server or workstation product (as an 
NLM on NetWare or from a command prompt on Windows-based 
platforms). 


This section provides detailed information on backing up a database 
using the following SQLUTIL commands: STARTBU and ENDBU. 


STARTBU 


The SQLUTIL -STARTBU command places a file or set of files into 
continuous operation for backup purposes. 


Format 
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SQLUTIL -STARTBU < datasourceName | @listFile >[/S | 


datasourceName 


@listFile 


/S 


Examples 


The data source name on which to begin continuous 

operation for backup. This name must match a data source 
name previously defined using the Pervasive.SQL ODBC 
DSN Setup utility in the ODBC Data Source Administrator. 


The name of a text file containing a list of the data source 
names on which to begin continuous operation. Separate 
these names with a carriage return/line feed. 


If SQLUTIL cannot put all of the files that make up the data 
source name in continuous operation, the utility does not 
put any of the files in continuous operation. 


By default, the SQL Maintenance utility stops at each full 
screen of output and waits for a keystroke before 
continuing. With the /S option, the utility continuously 
scrolls output on the screen. You cannot use /S on the 
command line if you specify a command file, but you can 
specify /S with a command inside a command file. 


The following example starts continuous operation on the university 


data source name: 


sqlutil -startbu university 
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The following example starts continuous operation on all databases 
listed in the DBBACKUP.TXT file. 


sqlutil -startbu @dbbackup.txt 


ENDBU 


The ENDBU command ends continuous operation on a data source 
name previously defined for backup. Execute this command after 
you have issued the STARTBU command and your backup utility has 
finished running. 


Format 


SQLUTIL -ENDBU < datasourceName | @listFile >[/S ] 


datasourceName The data source name for which to end continuous 
operation. 
@listFile The name of a text file containing the list of data source 


names for which to end continuous operation. The text file 
must contain the data source names separated with a 
carriage return/line feed. 


Typically, this list of data files is the same as the list used 
with the STARTBU command. 


/S By default, the SQL Maintenance utility stops at each full 
screen of output and waits for a keystroke before 
continuing. With the /S option, the utility continuously 
scrolls output on the screen. You cannot use /S on the 
command line if you specify a command file, but you can 
specify /S with a command inside a command file. 


Examples 


The following example ends continuous operation on the university 
data source name: 


sqlutil -endbu university 


The following example ends continuous operation on all databases 
listed in the DBBACKUP.TXT file. 


sqlutil -endbu @dbbackup.txt 
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Technical Details and Advanced Procedures for the Workgroup Engine 


This chapter explains how to get the most out of your Workgroup 
engine. 

= “Networking” on page 9-2 

= “Technical Differences Server vs. Workgroup” on page 9-4 

=m “Troubleshooting Workgroup Issues” on page 9-6 


m “Re-directing Locator Files” on page 9-8 
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Networking 


NetBIOS 


MicroKernel 
Router Deci- 
sion Algorithm 


Both the server and workgroup products are shipped with the same 
networking components. So you can upgrade a workgroup engine 
to a server engine. The client side requestors can connect to either 

type of engine. 


The Pervasive Network Services Layer searches for an engine on the 
network using NetBIOS as well as the other protocols previously 
supported; WinCE, Named Pipe, DNS, and NDS, and NetWare 
Bindery. The NetBIOS and DNS protocols can be used to contact a 
workgroup engine. Server engines on Windows advertise themselves 
with Named Pipes, so NetBIOS is not needed. NetWare servers are 
advertised using DNS, NDS, and NetWare Bindery. 


Even though SPX can be used on Windows 95/98/ME, it cannot be 
used by itself since these platforms do not use it as a connection 


protocol, it is only a transfer protocol. On Windows, NetBIOS must 
be bound to SPX/IPX in order to resolve the SPX address. 


Once the client requestor has found an IP, SPX or NetBEUI address, 
it will try to establish a connection to a MicroKernel engine using 
that transfer protocol. 


The client side MicroKernel router discovers Gateway ownership of 
files by following a well-established algorithm. 


Table 9-1 Gateway Discovery Priorities 





Priority Procedure 





1 Try to connect to a database engine on the same computer as 
the data files. 








2 Try to open the data files using the local engine (on the client 
machine). 
3 Find and connect to the Gateway engine that owns the files. 











The first thing the client-side router always tries is to connect to an 
engine on the same computer as the data. Because of this procedure, 
it is always more efficient to have an engine running where the data 
is. 


Networking 


Because the Pervasive Network Services layer uses so many different 
methods to find and connect to a remote database engine, there may 
be a time delay on the first attempt to open a file on a file server that 
does not have a database engine running. If Gateway Durability on 
page 4-31 is turned on, that connection will not be attempted 
thereafter because the router remembers each machine on which it 
fails to locate an engine. 


If the router cannot connect to an engine on the remote file server, 
the router then allows the local engine to attempt to open the remote 
files. The local engine first attempts to create a new locator file and 
take ownership of the remote directory. If the directory is already 
owned by another MicroKernel, the local engine returns Status Code 
116 to the router. 


Finally, the router attempts to discover the Gateway computer. It 
opens the locator file and reads the name of the Gateway engine. 
Then it sends the request to that engine. Notice that the router never 
tries to read a locator file unless it has received Status Code 116 from 
a MicroKernel first. This behavior means that in order to use the 
Gateway feature, you must have a local workgroup engine installed. 
If the attempt to open the remote files with the local engine fails 
because there is no local engine, the router does not try to read the 
locator file and no Gateway engine is found. 
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Technical Differences Server vs. Workgroup 


There are a few significant differences between a server engine and a 
Workgroup engine. This section explains the differences. 


Platforms 


The NetWare engine is a server engine only. Our Windows server 
engine requires Windows NT or Windows 2000. The Workgroup 
engine runs on any 32 bit Windows platform. 


User Interface 


While the Windows server engine runs as a service, the Workgroup 
engine is started as a regular process that has a tray icon for an 
interface. It must be put into the startup folder if there is local data 
to be shared. 


Network Connections 


The Windows server engine can use Named Pipes for operating 
system level file security and establishing connections. Since 
Windows 95/98/ME do not allow the creation of named pipes, the 
workgroup engine uses NetBIOS as a connection protocol. 


Authentication 


The server engine enforces file permissions set up in the operating 
system. As described earlier, the Workgroup engine does not 
authenticate users on its own. With the workgroup engine, if you 
can see the computer on the network, you can get to the data. This 
relaxed security is intended for small offices where security is not an 
issue and ease of use is. 


Gateway Support 


The Windows server engine creates locator files in remote directories 
where it opens files. This behavior allows it to be a designated 
gateway for remote files. The workgroup engine creates locator files 
everywhere it opens files, allowing the workgroup engine to 
dynamically adjust gateway ownership on a day-to-day basis. 
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Technical Differences Server vs. Workgroup 


User Counts 


The server engines start at 10 concurrent connections and the 
workgroup engine starts at 3. 


Asynchronous I/O 


Starting with Service Pack 2 of Pervasive.SQL 2000, the server engine 
for Windows NT/2000 makes use of Asynchronous I/O. This feature 
can provide a significant performance advantage. 


ODBC Client/Server 


The Workgroup release does not ship with the SQL Manager which 
allows the server engine to receive requests from a remote ODBC 
client. In a Workgroup environment, the ODBC driver (SQL 
Relational Database Engine, or SRDE) always runs on the client. This 
behavior means that only Btrieve requests are carried over the 
network. ODBC requests are processed locally and broken down into 
component Btrieve operations before the remote MicroKernel is 
contacted. 


In contrast, with a Server engine, both Btrieve and ODBC requests 
are processed at the server. 


The Workgroup engine’s thick client approach can be faster than a 
full client/server approach for simple queries and transactions, but it 
is slower when resolving complex queries where a lot of records are 
read and only a few rows are joined and returned as a result set. 
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Troubleshooting Workgroup Issues 


This section provides a few tips on troubleshooting problems in a 
Workgroup environment. 


Time delay on first connection 


If you are regularly experiencing a delay when the first file-open 
request is issued, see if these techniques help. 


If possible, make sure there is an engine running where the 
data is 


Connecting to an engine on the same machine as the data is the 
client's first priority when deciding where to send a file-open request. 
In order to make sure a workgroup engine is running, put an engine 
icon into the startup folder with the command 


C:\Pvsw\Bin\W3dbsmgr.exe -BTRV 


Another option on Windows 95/98 is to add the following registry 
key: 
[HKEY LOCAL MACHINE\Software\Microsoft\Windows\CurrentV 


ersion\RunServices] "Pervasive.SQL 2000 Workgroup" = 
"C:\\Pvsw\\Bin\\W3dbsmgr.exe -BTRV" 


This registry key starts the engine before anyone logs on. Note that 
the engine does not have a tray icon when started this way, because 
at the time of start-up, the “tray” has not been created. 


If you are running a gateway topology 


If you cannot run an engine where the data is, then the time delay 
during the first connection is a more important issue. Here are a few 
things you can do. 


1 Reduce the supported protocols in the client settings so that 
protocols that are not used in your network are not attempted. 
For example, if you do not have a NetWare MicroKernel on the 
network, which is true for most workgroup topologies, you can 
drop SPX/IPX as a supported client protocol. 


2 Use Gateway Durability. Gateway Durability is a client 
configuration setting that allows you to virtually eliminate the 
delay in making the first connection in a gateway environment. 
If Gateway Durability is turned on, it forces the client router to 
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write into the registry the names of computers it finds that do 
not have an engine running. Once a failure to connect happens, 
instead of remembering this server name only while the router is 
running in-process, it saves the name in the registry. The next 
time the application starts up, it does not try to connect to the 
engine where the data is. It immediately goes to the next step of 
determining the identity of the current Gateway. 


You can turn this setting on in PCC. Within PCC, double-click 
the icon representing the client computer. Double-click 
Configuration. Double-click Client. Click Access. Right-click on 
Gateway Durability and set it to On. 

Wag This feature is OFF by default since it fixes the topology. If you 
add a server engine or a Workgroup engine where the data is, you must 
turn this setting back to OFF on each of the clients where you turned it 
ON. Turning the setting off erases the registry of computers without an 
engine running, so you can turn it back ON immediately and a new list 
will be generated based on the new topology. 








Status Code 116 


Status 116 is a new MicroKernel Status Code which means that the 
file is being used by another MicroKernel engine acting as a Gateway. 
If your application receives a status code 116, it means that the 
MicroKernel router can read the locator file but cannot contact the 
engine running on the gateway computer. 


The first thing you need to do is find out who the gateway is. You can 
perform this task with the Gateway Locator utility. 


Next, use PSA network tests to try to connect to that computer. PSA 
can provide valuable information to isolate the problem. 


One situation when this could occur is when the two computers are 
separated by a router such that they can both see the file server but 
they cannot see each other. 
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Re-directing Locator Files 


This feature of Gateway engine operation guarantees transaction 
atomicity for multi-directory databases and also makes it easy to 
change the name of a Gateway engine across multiple data 
directories. 


Limitations of Previous Model 


Prior versions of the product supported two modes of Workgroup 
Gateway operation: 


m  apermanent Gateway database engine always serves the data files 
in a given directory—if the specified database engine is not up, 
then the data in that directory is not available. 


= with a dynamic Gateway, whichever database engine opens the 
data files first serves as the Gateway; this architecture is also 
referred to as a floating Gateway. 


This model was useful but had two limitations. First, if you had data 
in many different directories, and you wanted to change the 
permanent Gateway to a different engine, you had to use the 
Gateway Locator Utility to update the Locator File in every data 
directory (or update all the Locator Files by hand). 


Second, if you had a single database consisting of data files in more 
than one directory, it became possible for two different engines to 
handle data access within the same database, thus failing to ensure 
transaction atomicity. This situation could occur if the Gateway 
Locator files in the two directories pointed to different Gateway 
engines. For some users this may not be an issue, but transaction 
durability can only be guaranteed if a single database engine 
performs all data access operations on a given database. If 
transaction durability is important, then you must ensure that the 
same engine services all data files within the same database, 
regardless of their directory locations. 


New Behavior 


First, recall that the Pervasive.SQL client uses the following approach 
to access remote data files: 
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= First, attempt to connect to a database engine on the same 
computer as the data files. 


= Second, if no database engine is available on the remote 
machine, attempt to use a local engine to take ownership of the 
remote directory and create a Locator File. If a Gateway Locator 
File already exists, the local engine is not used. 


m Third, try to use the specified Gateway engine. 


It is important to remember that the Gateway configuration only 
goes into effect when there is no database engine available on the 
same computer as the data files. 


This feature allows a dynamic (floating) Gateway engine while at the 
same time preserving transaction durability for multi-directory 
databases on the same volume. This benefit is provided by a new type 
of Gateway Locator File that points to another Gateway Locator File. 
The new type is called a Redirecting Locator File. By having 
Redirecting Locator Files in directories A, B, and C that point to the 
Locator File in directory D, you can ensure that the Gateway engine 
specified by the Locator File in directory D services data files in the 
other directories as well. 


Regardless of whether the Locator file in directory D specifies a 
permanent Gateway or is dynamically created by the first engine to 
open those files, this architecture ensures that all the specified 
directories use the same Gateway engine. Likewise, if you decide to 
change the permanently assigned Gateway engine for several 
directories, Redirecting Locator Files allow you to do so by changing 
only one Locator File, rather than all of them. Thus, it is possible to 
specify that all data files on a given hard drive must use the same 
Gateway engine, with or without designating a permanent Gateway. 


Redirecting Locator File Requirements 


The first line of a Redirecting Locator File must start with “=>” and 
be followed by a path specifying another Locator File, which must be 
on the same drive. You can use any combination of forward slash and 
back slash in the path name. All slashes are converted to the type of 
separator used by the local operating system. 


If your specified path ends with a slash, the database engine assumes 
the default Locator File name (~PVSW~.LOC) and appends it to the 
path. If the specified path does not end with a slash, the database 
engine assumes that the path already contains the file name. 
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The table below lists the ways a Redirecting Locator File path can be 





specified: 
Table 9-2 Redirecting Locator File Path Descriptions 
Path Meaning 
=>\path_name Specifies the path from the root of the drive 


where the current Locator File is stored. 








=>.\path_name Specifies the path relative to the current 
directory. 
=>..\path_name Specifies the path relative to the parent 


directory of the current directory. 


You can assign multiple levels of redirection to these Locator Files. 
For example, you can have the first Locator File pointing to a second 
Locator File, the second Locator File pointing to a third Locator File, 
and so on. Each workgroup engine opens each Locator File 
sequentially, looking for the actual Gateway name. It stops searching 
once it has found the locator file that does not start with “=>”. The 
engine then assumes this Locator File specifies the Gateway engine. 


Creating Redirecting Locator Files 


As with any Locator File, a Redirecting Locator File is a plain text file. 
You can create Redirecting Locator Files by hand or 
programmatically. A Redirecting Locator File must be flagged as 
read-only, or it will be overwritten by the first engine to attempt to 
access the data files in that directory. 


> To Create a Redirecting Locator File 


1 Open Notepad or a text editor, and open a new text file. 


2 Decide where you are going to save the file when you are 
finished. You will save the file in the same directory as the data 
files which you want to redirect to another locator file. 


For example, if you want to ensure that the data files in C:\data 
are accessed by the same Gateway engine as other data files, then 
you will want to keep in mind the folder C:\data. 
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3 Type in => and the path name of the next Locator File. 


Continuing the example from the previous step, if you want the 
current data files in C:\data to be owned by the Gateway engine 
specified in the Locator File located in c:\moredata, then you 
would type the following: 


=>..\moredata\ (recommended) or 


=>\moredata\ (not recommended) 


In the first case, you are specifying a relative path from the 
current directory. In the second case, you are specifying an 
absolute path from the root of the current drive. In this 
particular example, both cases resolve to the same target 
directory. 





Note Pervasive strongly recommends that you use relative path names 
(starting with ./ or ../) in your Redirecting Locator Files, and that you 
use the same sharenames on all workstations to access the same data. 
Following these two recommendations can prevent errors that may 
occur with network path name resolution over mapped drives. 





4 Save the file as ~PVSW~.LOC in the directory where the data 


files exist that you want to specify a Gateway engine for. 


5 Close Notepad or the text editor. 


6 Flag the text file as read-only. 


To mark the file as read-only on Windows, you can use the 
Properties dialog box (right-click on the file icon) in Windows 
Explorer, or you can use the ATTRIB command in a DOS session 
or in a program: 


ATTRIB +R ~PVSW~ .LOC 


> To synchronize many data directories on a permanent 


1 


Gateway 


Either by hand or by using the Gateway Locator program, create 
a read-only (permanent) Locator File that does not redirect. It 
must specify a Workgroup engine to use as the Gateway. 


For example, your locator file may specify the computer named 
“workgroup1” as the Gateway engine, and the file may be located 
in C:\DATA\DB1. 
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2 For each of the other data directories that you want to use the 
Gateway engine specified in the previous step, you need to create 
a Redirecting Locator File in that directory. Each Redirecting 
Locator File must point to the file you created in the previous 
step. 


Continuing the example, each Redirecting Locator File in 
C:\DATA\DB2 and C:\DATA\DB3 would then contain the 
following text: 


=>..\DB1\ 


This causes any engine reading this file to follow the relative path 
and search the specified directory C:\DATA\DB1 for another 
Locator File. In this case, the specified directory contains a 
Locator File that names “workgroup1” as the Gateway computer. 


» To synchronize many data directories on a dynamic 
Gateway 


1 Follow the steps above, only in step #1, ensure that the Locator 
File is writable, not permanently-assigned. 


In this case, remember that if no engines are accessing any data 
files in the redirecting hierarchy, then there will be no Locator 
File in the target directory. This is normal. The dynamic Locator 
File is created each session by the first engine to access the data, 
and the file is deleted when the last user session ends. It is 
permissible to have Redirecting Locator Files that point to a data 
directory that has no Locator File in it. In this case, the first 
engine to open those data files creates the Locator File. 


Example 


Using the example Locator Files shown in Figure 9-1, the Redirecting 
Locator File on the left forces the database engine to go up one 
directory, then look in the sub-directory newdir for another Locator 
File with the default name (~PVSW~.LOC). This Locator File, in 
turn, specifies that the Workgroup engine on the computer named 
ntserver1 is the correct Gateway engine. As a result, the database 
engine on ntserver1 is used to access the data files in the directory 
mydir. 
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Figure 9-1 Redirecting Locator File Example 


mydir/-pvsw-.loc newdir/-pvsw-.loc 








=>../newdir/ ntserver1 
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Using Monitor to Oversee Database Resources 


This chapter includes the following sections: 

m “Monitor Utility Overview” on page 10-2 

m “Setting Monitor Utility Options” on page 10-5 

= “Monitoring MicroKernel Resources” on page 10-6 


= “Monitoring SQL Interface Resources” on page 10-18 
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Monitor Utility Overview 


Starting the 
Monitor Utility 
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The Monitor utility allows you to monitor Pervasive.SQL activities 
on a server. It provides information that is useful for both database 
administration and application programming diagnostics. In 
Pervasive.SQL 2000i, it has been enhanced to support monitoring of 
the ODBC communications server. Related enhancements include: 


= Display users (connected via ODBC Client), client info (host 
name, IP address, application), data source name, connection 
info (status, connection time, active/idle period) 


= Auto-refresh of user/connection info 





y 


— Note These features require authentication to view remotely. 


The following table shows the versions of the Monitor utility and the 
supported platforms. 








Monitor Utility Supported Platforms 
Win16 Windows 3.x clients 
Win32 Windows NT servers 


Windows 95/98 and Windows NT 
clients 














The Monitor utility provides a “snapshot” of server activity at a 
recent point in time. How recent the snapshot is depends on the 
polling interval. For information on how to set the polling interval, 
see “Setting Monitor Utility Options” on page 10-5. 


>» To start Monitor from 32-bit Windows 


1 From the Start menu, select Pervasive, then arrow to 
Pervasive.SQL 2000i, then Utilities, then Monitor. You can also 
select the Monitor from the Pervasive Control Center Tools 
menu. 

» To start Monitor from Windows 3.x 

1 Choose Monitor in the Pervasive.SQL 2000i program group. 


The Pervasive.SQL Monitor Utility main dialog box is displayed. 


Monitor Utility Overview 


Figure 10-1 Monitor Utility Main Dialog Box 


“| Pervasive Software Monitor Utility = 





























When you start the Monitor utility, it connects to the local 
engine by default. However, you can also monitor remote server 
engine resources by connecting to the remote server. 





Note If dialog boxes are currently open in the Monitor utility window, 
you cannot connect to or disconnect from a remote server. Close the 
open dialog boxes before proceeding. 





» To connect to a remote server 


1 Choose Connect on the Options menu. The Connect to Remote 
Server dialog box appears, as shown in Figure 10-2 on page 10-4. 
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Figure 10-2 Connect to Remote Server Dialog Box 


il Connect to Remote Server | x} 


Somme: [id 
enm | 
am MMMM 


Cancel | 





Enter the server name in the Server Name box, along with your 
user name and password for that server. To be authenticated, you 
must be a user with administrative rights on the remote server or 
in the domain if you are logged into the domain, or a member of 
Pervasive _Admin on the remote server or domain server. 


To disconnect from a server, choose Disconnect on the Options 
menu. 


Setting Monitor Utility Options 





Setting Monitor Utility Options 


» To configure the Monitor utility options 


1 Choose Settings from the Options menu. The Monitor Settings 
dialog box appears, displaying the current settings. 


Figure 10-3 Monitor Settings Dialog Box 


E Monitor Settings xi 


ttings on E i 
IV Save Window Layout on Exit 


Refresh Rate (Seconds): | 





Cancel | Help | 





2 You can specify the following options: 





Save Settings on Exit | Select this check box to save all configuration settings 
when you close the Monitor utility. The Monitor utility saves 
both the settings in this dialog box and the automatic- 
refresh option in the various dialog boxes. 





Save Window Layout | Select this check box to save the state (open or closed) 
on Exit and screen location of all open windows. When you start 
the Monitor utility again, these windows are automatically 
opened and positioned for local file server monitoring. This 
enables you to easily reproduce your preferred layout. 


NOTE: A user connecting to a remote system must first 
close all windows which are open. 





Refresh Rate Specifies the time interval with which the Monitor utility’s 
(Seconds) display refreshes itself. The refresh rate is measured in 
seconds. The default setting is 4. You can enter integer 
numbers only. 


It is important not to set this number too low, or the monitor 
utility will refresh itself frequently, affecting the 
performance of your database engine. This is especially 
true if you are running the Monitor utility local to your 
engine. 














3 Click OK to save the settings or Cancel to close the dialog box 
without saving changes. 
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Monitoring MicroKernel Resources 


Setting Screen 
Refresh Op- 
tions 


Viewing Active 
Files 
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This section describes the following options for monitoring the 
MicroKernel: 

m “Setting Screen Refresh Options” on page 10-6 

= “Viewing Active Files” on page 10-6 

m “Viewing User Information” on page 10-10 

= “Viewing MicroKernel Resource Usage” on page 10-13 


= “Viewing MicroKernel Communications Statistics” on page 10- 
14 


You can refresh the information in the Monitor utility dialog boxes 
either automatically or manually, as follows. 


=» Automatically: select the Automatic Refresh check box. The 
utility updates the dialog boxes at the Refresh Rate specified in 
the Monitor options (available via Settings on the Options 
menu). 


= Manually: Click Refresh. 


>» To view active MicroKernel files 


= Choose Active Files from the MicroKernel menu. The 
MicroKernel Active Files dialog box appears, as shown in Figure 
10-4 on page 10-7. This dialog box shows all the active files for 
the MicroKernel. 
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Figure 10-4 MicroKernel Active Files Dialog Box 


HA AA Files Connection: mjf-ntws 


Active MicroKernel Files: 6 Selecled File's Handles: 2 
e: \pysw\demodata\alttrib. ddf 
e:\pyswidemodata\class.mkd 
c:\pvsw\dcmodata\ficld. ddf 
sw\demodata\file. ddf 


e: \pysw\demodata\index.ddl 
e:\winnt\dbnames.cfg 





File Information: file.ddf —________, -Handle Information mlalcona ——— 
Page Size: 512 Connection Number: HA 
Read-Dnly Flag: No Task Number: 1 
Record Locks: No Site: Remote 
Transaction Lock: No Network Address: T:17216.0.219 

Open Mode: Normal 
Record Lock Type: Nune 
Wail Slate. None 
Trarisactiun State. None 




















tn | tn | 


In the upper left of the dialog box, the Monitor utility displays 
the Active MicroKernel Files list. This scrollable list contains the 
complete path of all open files in alphabetic order. 





» To view more information about a particular file 


Select the desired file in the list. View the information in the 
lower left corner of the window. 


In the upper right ofthe MicroKernel Active Files dialog box, the 
Monitor utility displays the Selected File's Handles list. This 
scrollable list contains the active handles (users) associated with 
the selected file. Each handle is represented by a user name 
(typically the login ID of the user), or by an index into the 
engine's client (user) list. 


» To view more information about a particular user 
Select the desired user in the Selected File’s Handles list. 


Some handles have an agent identifier, a two letter code that 
specifies the application that initiated the session. 
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Table 10-1 lists the agent IDs used by Pervasive.SQL 
components. 


Table 10-1 Agent IDs 
































Agent ID Application or Component 

BT Maintenance utility for the Btrieve Interface (BUTIL) 
DE Database Services client 

DC Database Services login 

DR DOS client Requester 

ML MicroKernel logging and roll forward 

NR Windows 95 and Windows NT client Requester 

NX Maintenance utility for the SQL Interface (SQLUTIL) 
PU Pervasive.SQL utilities 

SC SQL Interface login 

SE SQL Interface 

WR Windows client Requester 














The File Information box displays detailed information about 
the selected file. The Handle Information box displays detailed 
information about the selected handle. 
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File Information 


The File Information box displays the following information about 


each file: 


Page Size 


Read-Only Flag 


Record Locks 


Transaction Lock 


Indicates the size in bytes of each page in the file. 


Indicates whether the file is flagged as read-only by the 
operating system. 


Indicates whether any of the active handles for the selected file 
have record locks. Any application can read a locked record, 
but only the application that placed the lock can modify or 
delete the record. A record lock exists only as long as the 
application that opened the file is updating a record. Yes 
indicates that one or more record locks are applied to the file; 
No indicates that no records are locked. 


Indicates whether any of the active handles for the selected file 
have a transaction lock. A transactional file lock exists only as 
long as the application that opened the file is processing a 
transaction. 


Handle Information 


The Handle Information box displays the following information 


about each file: 


Connection 
Number 


Task Number 


Site 


Network 
Address 


Displays the network connection number of the client. If the 
client does not have a network connection, this field displays 
NA (for not applicable). 


Displays the process-supplied task number for processes 
originating at the server, or a Windows client. If the process 
originates at a DOS client, this field contains the 
communications protocol socket number. 


Specifies the location of the user process (local or remote). 


Identifies the location of the calling process on the network. If 
the calling process is SPX, then network node/network address 
is preceded by S: such as S: 65666768 00000000001. If the 
calling process is TCP/IP, the dotted-decimal notation of the IP 
number is preceded by T: such as T: 180.150. 1.24. 
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Open Mode Indicates the method the application uses to open the specified 
handle of the file. Valid open modes are: 


Normal—The application that opened the file has normal 
shared, read/write access to it. 


Accelerated—The application that opened the file has shared 
read/write access. 


Read-only—The application that opened the file has read-only 
access; it cannot modify the file. 


Exclusive—The application that opened the file has exclusive 
access. Other applications cannot open the file until the calling 
application closes it. 


The Monitor utility also specifies all open modes as non- 
transactional or shared locking when applicable. 


Record Lock Displays the type of record lock(s) currently held by the handle. 
Type The possible record lock types are Single, Multiple, and None. 


Single-record locks enable a user to lock only one record at a 
time. Multiple-record locks enable a user to lock more than one 
record at a time. 


Wait State Indicates whether the user is waiting due to some type of lock 
on this handle: Waits for Record Lock, Waits for File Lock, or 
None. 

Transaction Displays the state of the transaction lock currently held by the 

State handle. The possible transaction types are Exclusive, 


Concurrent, or None. 


Viewing User You can view a list of current users and files, as well as file handles for 
Information each user. 
» To view MicroKernel user information 


= Choose Active Users on the MicroKernel menu. The 
MicroKernel Active Users dialog box appears, as shown in 
Figure 10-5. 


10-10 


Monitoring MicroKernel Resources 


Figure 10-5 MicroKernel Active Users Dialog Box 


fi MicroKernel Active Users Connection: Local | x! 
Active MicroKernel Users: 1 Selected User's Handles: 1 
unknown c:\pysw\demodata\billing mkd 











- User Information: unknown. , Handle Information: billing.mkd- 
Connection Number: NA | Open Made: Normal 
Task Number: 1079 || Record Lock Type: None 
ae E na Wait Slate: None 
Address: = 

Lada leek 0 Transaction State: None 
Transaction State: None 

Records Read: I Automatic Refresh 


Records Inserted: 


0 
D 

Records Deleted: n Delete Curent User Close | 

Records Updated: 0 Delete All U | Help 

Disk Accesses: 0 = | 

Cache Accesses: 0 








In the upper left of the dialog box, the Monitor utility displays 
the Active MicroKernel Users list. This scrollable list contains 
the names of active users in alphabetic order. Each user is 
represented by a user name (typically the login ID of the user) or 
by an index into the engine's client (user) list. 


» To receive more information about a particular user 
Highlight the desired user in the list. 


Each client is represented by either a user name (typically the 
login ID of the user) or an index into the engine's client (user) 
list. Table 10-1 on page 10-8 lists the agent IDs used by 
Pervasive.SQL components. See“User Information” on page 10- 
12 for specific details about the information available. 


In the upper right of the MicroKernel Active Users dialog box, 

the Monitor utility displays the Selected User's Handles list. This 
scrollable list contains the active handles (files) associated with 

the selected user. The MicroKernel creates a handle each time a 
user opens a file; therefore, a single user can have several handles 
for the same file. 
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> To view more information about a particular file handle 


= Highlight the desired handle in the list. See“Handle 
Information” on page 10-13 for specific details about the 
information available. 


User Information 


The User Information box displays the following detailed 
information for the selected user handle: 


Connection See “Connection Number” on page 10-9. 
Number 

Task Number See “Task Number” on page 10-9. 

Site See “Site” on page 10-9. 


Network Address See “Network Address” on page 10-9. 
Locks Used Indicates the number of locks the user is currently using. 
Transaction State Displays the type of transaction lock the user currently 


holds. The possible transaction types are Exclusive, 
Concurrent, or None. 


Records Read Displays the number of records read since the user first 
opened a file. 

Records Inserted Displays the number of records the user has inserted. 

Records Deleted Displays the number of records the user has deleted. 


Records Updated Displays the number of records the user has updated. 

Disk Accesses Indicates the number of times the user required a disk 
access. You will not see any information for disk accesses 
for files that have just been opened. 


Cache Accesses Displays the number of times the user required a cache 
access. 
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Handle Information 


When you click on a specific file handle, the following information 
about that handle is displayed in the lower right corner of the 
window: 


Open Mode See “Open Mode” on page 10-10. 


Record Lock Type See “Record Lock Type” on page 10-10. 


Wait State See “Wait State” on page 10-10. 


Transaction State See “Transaction State” on page 10-10. 


Deleting Current Users 


> 


> 
1 


To delete a user 


Highlight the user name and click Delete Current User button. 
Deleting the current user removes the user from the list of active 
users of the MicroKernel and terminates the user's connection to 
the Communications Server. All open files for the user are closed 
and all allocated resources are freed. 


You can also click Delete All Users which deletes all of the 
current MicroKernel users. 


To view MicroKernel resource usage 


Choose Resource Usage from the MicroKernel menu. The 
MicroKernel Resource Usage dialog box appears, as shown in 
Figure 10-6 on page 10-13. 


Figure 10-6 MicroKernel Resource Usage Dialog Box 








Current Peak Maximum 
Files: 1 7 20 MATA 
Handles: 2 14 60 l | 
Clients: 3 10 30 I. 
Worker | hreads: 1 1 128 Tr oo 
Licenses in Use: 0 2 5 I. 
Transactions: U 1 Unlimited 
Locks: 0 446 Unlimited 

AAA KK A e | 
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This dialog box allows you to view the total resources in use by 
the MicroKernel since it was loaded.The MicroKernel Resource 
Usage dialog box shows the following statistics for each resource: 


+ Current — Shows the present value for the field. 
+ Peak — Shows the highest value for the field since the 
MicroKernel was started. 


+ Maximum -— Shows the highest value allowed for the field. 


Files Indicates the number of active files. 


Handles Indicates the number of active handles. The MicroKernel 
creates a handle each time a user opens a file; therefore, a 
single user can have several handles for the same file. 


Clients Indicates the number of clients accessing the MicroKernel. A 
workstation can have multiple clients accessing the engine 
simultaneously. You set the maximum for this field with the 
Configuration utility (see “Active Clients” on page 4-2). 


Worker Threads Indicates the number of concurrent MicroKernel processes. 


Licenses in Use Indicates the number of connected client licenses in use as 
defined by your licensing agreement. In this case, the 
maximum shows the number of users your licensing 
agreement allows. 


Transactions Indicates the number of transactions. The maximum for this 
field is unlimited. 


Locks Indicates the number of record locks. The maximum for this 
field is unlimited. 


Viewing Micro- > To view MicroKernel communications statistics 


Kernel Commu- 1 Choose Communications from the MicroKernel menu. The 

ni cati on s MicroKernel Communications Statistics dialog box appears, as 

Statistics shown in Figure 10-7. This dialog box shows you the network 
requests, worker threads, and sessions in use by the 
Communications Server since it was loaded. 
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Figure 10-7 MicroKernel Communications Statistics Dialog Box 





The MicroKernel Communications Statistics dialog box shows 
the following statistics for several of the communications 
resources: 

+ Current — Shows the most recent value for each field. 


+ Peak — Shows the highest value for the field since the 
Communications Manager was started. 


+ Maximum - Shows the highest value allowed for the field. 
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You can monitor the activity of the following communications 
resources in the MicroKernel Communications Statistics dialog 
box: 


Total Requests Indicates the number of requests the Communications 
Processed Manager has handled from workstations or remote, 
server-based applications. 


Total — Indicates the number of requests processed 
since the Communications server was loaded. 


Delta — Indicates the number of requests since you first 
invoked the Communications Statistics dialog box. To 
reset this number to zero, click Reset Delta. 


SPX Requests Indicates the number of SPX requests the 
Processed Communications Manager has handled from clients or 
remote, server-based applications. 


Total — Indicates the number of requests processed 
since the Communications server was loaded. 


Delta — Indicates the number of requests since you first 
invoked the Communications Statistics dialog box. To 
reset this number to zero, click Reset Delta. 


TCP/IP Requests Indicates the number of TCP/IP requests the 
Processed Communications Manager has handled from clients or 
remote, server-based applications. 


Total — Indicates the number of requests processed 
since the Communications server was loaded. 


Delta — Indicates the number of requests since you first 
invoked the Communications Statistics dialog box. To 
reset this number to zero, click Reset Delta. 


NetBIOS Requests Indicates the number of NetBIOS requests the 
Processed Communications Manager has handled from clients or 
remote, server-based applications. 


Total — Indicates the number of requests processed 
since the Communications server was loaded. 


Delta — Indicates the number of requests since you first 


invoked the Communications Statistics dialog box. To 
reset this number to zero, click Reset Delta. 
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Indicates the number of times the AutoReconnect 
feature has timed out when attempting to reconnect to 
clients. 


Total — Indicates the number of requests processed 
since the Communications server was loaded. 


Delta — Indicates the number of requests since you first 
invoked the Communications Statistics dialog box. To 
reset this number to zero, click Reset Delta. 


Indicates the number of times the AutoReconnect 
feature has successfully recovered from a connection 
timeout. 


Total — Indicates the number of requests processed 
since the Communications server was loaded. 


Delta — Indicates the number of requests since you first 
invoked the Communications Statistics dialog box. To 
reset this number to zero, click Reset Delta. 


Indicates the number of remote requests that the 
MicroKernel is currently processing. Local requests are 
not included in this statistic. For the total number of 
remote and local threads being processed, see the 
Resource Usage dialog box. You set the maximum for 
this field with the Configuration utility (the 
Communications Threads option on page 4-22). 


Worker threads are also used to process Monitor utility 
requests, so you may not see the number of current 
worker threads drop below one. This is normal. 


Indicates the number of remote clients connected to the 
Communications Manager. You set the maximum for 
this field with the Configuration utility (the Number of 
Sessions option on page 4-4). 


Indicates the number of remote clients connected via 
SPX to the Communications Manager. 


Indicates the number of remote clients connected via 
TCP/IP to the Communications Manager. 


Indicates the number of remote clients connected via 
NetBIOS to the Communications Manager. 
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This section describes the following options for monitoring the 
Relational Database Engine: 


= “Monitoring Active SQL Connection Manager Sessions” on 
page 10-18 

= “Understanding Session Information” on page 10-18 

m “Refreshing the Active Session List” on page 10-19 


m “Deleting an Active Session” on page 10-20 


» To view active SQL Connection Manager Sessions: 


1 Choose Active Connections from the SQL menu on Monitor’s 
main screen. 


2 The SQL Connection Manager Active Sessions window appears, 
as shown below. 


Figure 10-8 SQL Connection Manager Active Sessions Dialog Box 


E SQL Connection Manager Active Sessions Connection: Local 
















Active Sessions: 1 


Close | 
Help | 


[Y Automatic Ketresh 





Scasion Information: 


Client Host Name: psr 

Client IP Address: 177 18 5175 

Client Application: Microsoft ODBC SDK v2.0 
Data Source Name: EngineDSN 

Connection Status: Idle 


Aclive/Idle Period (ms): 5838908 
Total Connection Time (s): 5891 





The SQL Connection Manager Active Sessions dialog box contains 
information about connected users, data sources, and applications 
in use. 


Refreshing the 
Active Session 
List 
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The top Active Sessions label displays the number of active SQL 
Connection Manager sessions. The User Name list box displays the 
list of connected user names. User Name is set by default to the 
Windows login ID. If this is unavailable, User Name is set to 
“unknown”. 


More information about the selected User Name is displayed in the 
Session Information group box. By default, it displays the following 
information about the user: 


Client Host Name This is the client’s machine or host name of the selected 
User Name. If unavailable, this is set to “Unknown.” 


Network Address This is the client's IP or NetWare address for the 
selected User Name. If unavailable, this is set to 
“Unknown.” 

Client Application This is the connected application or module. If 


unavailable, this is set to “Unknown.” 


Data Source Name This is the name of the engine DSN referenced by the 
client application. 


Connection Status This is the connection status for the selected User 
Name. A possible status may be “Active”, “Idle”, “Dying”, 
or “Unknown” if status is unavailable. 


Active/ldle Period This refers to the duration of time, in milliseconds, since 
the connection has been active or idle. 


Total Connection Time This refers to the duration of time, in seconds, since the 
connection has been established. 


1 Click Refresh Session List or enable the Automatic Refresh 
checkbox. 


2 To change the Automatic Refresh rate, choose Settings from the 
Options menu on Monitor’s main dialog box. The Monitor 
Settings dialog box appears, as shown below. The default refresh 
rate is 4 seconds. 


10-19 


Monitoring Database Resources 


Figure 10-9 Monitor Settings Dialog Box 





i= Monitor Settings 


Mi 











Deleting an Ac- 1 Select the session to be deleted by clicking on the desired user 
tive Session name in the User Name list box. 


2 Click Delete Session and the SQL Connection Manager deletes 
the selected session. 
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Btrieve Operations Performed with the Function Executor Utility 


This chapter discusses the following topics: 


= “Function Executor Overview” on page 11-2 
m “Starting the 32-bit Function Executor Utility” on page 11-3 


= “Overview of the Function Executor Main Window” on page 11- 
10 


= “Performing Operations” on page 11-13 
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Function Executor Overview 


The 16-bit and 32-bit Function Executors run on Win16 and Win32 
platforms for Pervasive.SQL 20001 server and workstation products. 
With this interactive utility, you can learn how Btrieve operations 
work. By allowing you to execute Btrieve operations one at a time, 
the Function Executor enables application developers to simulate the 
operations of a Btrieve application, which can help in testing and 
debugging your program. 


The Function Executor is primarily a tool for application developers; 
this chapter assumes a basic knowledge of Btrieve operations. For 
more information about Btrieve operations, refer to the API 
Programmer’s Reference that is available with the Pervasive.SQL 
Software Developer's Kit (SDK). 


Starting the 32-bit Function Executor Utility 





Starting the 32-bit Function Executor Utility 


> 
1 


á Pervasive Function Executor 
File Get GetExt Step Updates View Tools Window Help 


To start the Win32 Function Executor utility: 


Click the Start button, and point to Programs. Point to 
Pervasive, then Pervasive.SQL 2000i, and then Utilities. Select 
Function Executor from the list of Utilities. 


+ Alternatively, you can access the Function Executor from 
within the Pervasive Control Center. Click on Tools and 
select Function Executor. 


The main window (Figure 11-1) appears. 


Figure 11-1 32-bit Function Executor Main Window 
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Features of the 
Win32 Function 
Executor 





The Win32 version of the Function Executor includes all the 
functionality of the Win16 utility as well as some new features. Many 
ways of performing familiar Win16 operations are different in the 


Win32 version. These include the features listed below. 
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Editor Status Bar 


The last/current status code is shown in the editor window's status 
bar at the bottom of the window for the open file, and appears red if 
the last status was not zero. 





Placing the mouse cursor over the status code shows a description of 
the status and what operation caused it. 


Pos = 0 Hex(38] Dec(56) Asc(8) | 


When your cursor is in the input area on the main window of the 
Function Executor, the status bar displays the offset within the 
buffer: the hex, the decimal, and the ASCII value of the byte you are 
presently on. 





1of1 


The status bar also indicates how many operations have been 
performed when there are multiple items in the queue. Normally this 
displays 1 of 1, but if you are executing multiple operations, it will 
display the count as the operations are executed. 


The status bar also displays when you are in a transaction. 


Statistics 


Clicking on the File Statistics icon displays a dialog box listing the 

currently-open file’s statistics. You can print these statistics to a text 
file or save them to a description file usable by BUtil create (you may 
also create a new blank file with the same characteristics.) Previously, 


Starting the 32-bit Function Executor Utility 


these items had to be manually picked out of the data buffer after 
executing a Btrieve operation 15. 
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Get and GetExt 


From the Get menu, you can retrieve the First, Next, Previous, and 
Last records in the table. The GetExt menu includes the Goto 
Percent, Get Position, and Find Percent commands. 


The Get and GetExt commands are available from both the menu 
bar and toolbar. The toolbar offers Step (Physical) and Get (Logical), 
allowing you to move either through the natural order of the file 
(Physical) or in a specific order (Logical). 


Goto Percent allows you to choose whether to jump to a point within 
the physical layout of the file, or down any key path, limited to the 
keys defined in the file. You can also set lock biases using the option 
buttons in the Locks group box. 





Goto Percent 
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Find Percentage is the opposite of Goto Percent. It tells you how far 
into the data you are, depending on whether you are stepping 
through the file logically or physically. 


Find Percentage | x} 


File: c:\pysw'demodata\person.mkd 
C Physical (* Logical 
Key Value 


fi y] [Curbow 


Result 
12.29% 






























Reset Client ID 


Clicking on the Reset Client ID icon resets the current client 
connection (Btrieve operation 28) and closes all files open by the 
Function Executor. 


Btrieve Stop 


Clicking on the Btrieve Stop icon terminates transactional services 
(Btrieve operation 25) and closes all open files. 


Version Call 


Clicking on the Version Call icon displays information about the 
version of Pervasive.SQL (Btrieve operation 26) that you are 
running. If no file is open, you will see information only about the 
requester .dlls. On a server, or if a file is open, you will see 
information about the server and requester .dlls. 


Starting the 32-bit Function Executor Utility 
Transaction Toolbar 


5 Pervasive Function Executor 


File Get GetEvt Step Updates View Tools Window Help 
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The Transaction toolbar lets you start, stop, and abort transactions 
extremely fast. You can set all aspects of the Transaction API through 
this toolbar, and the operation is executed immediately. The 
Transaction status also appears on the main window status bar, since 
it affects all open files for the client ID. 


Viewing as Any Data Type 


When a file is open, you can right-click on any position in the buffer 
and select Show As. A dialog appears in which you can view the bytes 
at the chosen buffer position as any data type. 


a View as Any Data Type Eg 
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Refresh Close | 


Table lists controls available only in the Win32 version of the 
Function Executor. The Win32 Function Executor includes all of the 
controls available in the Win16 version as well as these controls. 


Table 11-1 Win32-Only Function Executor Controls 











Control Description 
Repeat Allows you to repeat commands. 
Create Allows you to create a new file. 
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Table 11-1 Win32-Only Function Executor Controls 














Control Description 

File Gives information from the BSTAT function. You can print these 
Statistics statistics. 

MDI The Multiple Document Interface permits the opening of multiple 





files. 








Starting the 16-bit Function Executor Utility 





Starting the 16-bit Function Executor Utility 


> 


1 
2 
3 


if Btrieve Function Executor Al ES 


File: || Transaction: No 


-Operati 
caeh e e I Get Key Bias (+50) 
urrent: ast 


List: [Open (0) >] Read Lock Bias: [No Lock El 


To start the Win16 Function Executor utility 
Open the Pervasive.SQL 2000 program group. 
Choose Function Executor (Win16). 


The main window (Figure 11-2) appears. 


Figure 11-2 16-bit Function Executor Main Window 
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11-9 


Testing Btrieve Operations Using the Function Executor 





Overview of the Function Executor Main Window 


11-10 


Table 11-2 lists the controls available in the Win16 version of the 
Function Executor. Some of the controls correspond to Btrieve 
Interface function parameters. 


Table 11-2 Win16 Function Executor Controls 





Control 


Description 





File 


Lists the full path of all open data files and displays the current open 
file. You can move among open files, but you cannot open a file 
using this box. To open a file, refer to “Opening a File” on page 11- 
13. 


This control corresponds with the Position Block parameter. 
Because each file name represents a position block, a file name 
can appear more than once in the list if the file has been opened 
more than once. 





Transaction 


Indicates whether the current operation occurs inside a transaction 
and the type of transaction, as follows: 


Exclusive — Exclusive transaction. 

Concurrent — Concurrent transaction. 

Conc+ModLk — Concurrent transaction with Modify Lock (+500) 
bias. 























Operation 

Current Specifies the current operation code plus its bias (if any). The 
default is 0. If you are familiar with Btrieve operation codes, you can 
enter the desired code. Otherwise, use the List box to specify an 
operation. This control corresponds with the Operation Code 
parameter. 

Last Displays the code of the last operation that was executed on the 
current file. 

List Lists all Btrieve operations and their codes. The default is Open (0). 
You can move quickly through the list by entering the first letter of 
the operation you want to perform. 

Get Key Bias | Instructs the MicroKernel to return only a key value, not a data 

(+50) record, on the current Get operation. 

Modify Lock | Instructs the MicroKernel to set a no-wait lock bias on an insert, 

Bias (+500) | update, or delete operation executed within a concurrent 





transaction. 
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Control 


Description 





Read Lock 
Bias 


Adds one of five biases to the current operation, as follows. For files 
in exclusive transactions, the MicroKernel ignores any lock bias 
values you specify explicitly. 


No Lock — Performs no locking. (Default) 

Single Wait (+100) — Attempts to lock a single record; ifthe record 
is already locked, it waits until the record is free. 

Single No Wait (+200) — Attempts to lock a single record and 
returns control if the record is already locked. 

Multiple Wait (+300) — Attempts to lock multiple records in the 
same file; ifthe records are already locked, it waits until the records 
are free. 

Multiple No Wait (+400) — Attempts to lock multiple records in the 
same file and returns control if the records are already locked. 





Key 


Number 


For most Get operations, specifies a key number, or index path, to 
follow for the current operation. For other operations, specifies such 
information as file open mode, encryption, or logical disk drive. This 
control corresponds with the Key Number parameter. 





Buffer 


Specify the path for the data file for which you want to perform a 
Btrieve operation. 





Position 


Indicates the position of the cursor within the Key buffer. 





Hex Display 


Clear 


Data 


Click this check box to view the data in Hex format. 


Click this button to clear the buffer field so that you can enter 
another data file. 





Length 


Specifies the length (in bytes) of the Data Buffer. The default is 
1024. For every operation that requires a data buffer, you must 
specify a buffer length. On many operations, the MicroKernel 
returns a value to the Data Length. Generally, you should always 
specify a Data Length before you execute an operation. This control 
corresponds with the Data Buffer Length parameter. 





Buffer 


Specifies a data value. For read and write operations, the Data 
Buffer contains records. For other operations, the Data Buffer 
contains file specifications, filtering conditions, and other 
information the MicroKernel needs for processing the operation. 
This control corresponds with the Data Buffer parameter. 





Position 


Indicates the position of the cursor within the Key or Data Buffer. 








Hex Display 





Click this check box to view the data in Hex format. 
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Table 11-2 Win16 Function Executor Controls 














Control Description 

Clear Click this button to clear the buffer field so that you can enter 
another data file. 

Status Displays a numeric status code returned by the MicroKernel and a 
brief message explaining the result of a Btrieve operation. For 
detailed information about these status codes and messages, refer 
to the Status Codes and Messages manual. 

Execute Performs the currently specified operation. 














Note The Win16 version of the utility performs wait lock simulation. 
Win16 applications cannot go into a wait loop. If you ask for a record 
lock using a Wait Bias and the record is locked by someone else, the 
engine returns Status Code 84 or 85 immediately to the application. 


The Win16 Function Executor utility retries the operation until it gets 
the record or you click Abort which is displayed in the lower right 
corner of the Main window. 








Performing Operations 





Performing Operations 


Opening a File 


Because Btrieve provides many operations, this chapter cannot 
explain them all. The following sections discuss some common 
operations as well as some new ways of performing them with the 
Win32 Function Executor. 


> 


oh 


a Aà O N 





Note In the Win16 Function Executor, to perform an operation, 
specify values for the appropriate controls and click Execute. In the 
Win32 Function Executor, selecting options from all menus performs 
the intended operation immediately. It does not fill in the grid and wait 
for you to execute the command as the Win16 Function Executor does. 
Also, closing the form in the Win32 Function Executor does a B_Close 
for each open file. This is new; the Win16 Function Executor forces you 
to do the close operation manually. 





To open a data file with the Win16 Function Executor: 
Select Open (0) from the List box or enter 0 in the Current box. 
Enter the path of a data file in the Key buffer. 

[Optional] Enter the owner name into the Data buffer. 
[Optional] Enter the Open Mode into the key number. 


Click Execute or press Enter. 


To open a data file with the Win32 Function Executor: 


From the File menu, select Open. The following dialog box 
appears: 
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Figure 11-3 Open Btrieve File Dialog Box 


Open Btrieve File [x] 
> Filename 








E Browse | 














Diner Name Mode 
(Dn @ Normal (0) 
C Accelerated [-1] 
Client ID Sharing C Read-Only — [-2) 


suto | | © Default 
T Use Aut E C Verify (3) 

















ae € Single Engine (-32) 
[ro fo =| e MultiEngine (-64) $ Esclusive (4) 


Cancel | Hep | 











~~ Note Client ID: If you have Use disabled, the Function Executor will 
use a BTRV() function call. If Use is enabled, it will use a BTRVID() 
function call for each operation you execute on this file. With Auto 
enabled, the Function Executor will generate a client ID for you. If you 
have Auto disabled, then you may enter values manually. 





2 Click Browse. 
3 Double-click on the desired filename. 
Creating a > There are two options in creating a Btrieve file with the 


Btrieve File Win32 Function Executor. If a file is already open, you 
can clone it; otherwise you can start from scratch. 


Method 1: Using a current file as a template 


1 From the File menu, select New. The following dialog box will 
appear: 
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Figure 11-4 Modify File Definition Dialog Box 
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2 You can manipulate keys from this dialog as well. You can Add, 


Create, or Insert Segments from the Key menu. You can also save 
the new file as a description for use with BUtil create. Select Save 
As Desc and indicate the name and location where you would 
like the file saved. 


To create the file, click Create. This will open the file and display 
a message indicating success. 


Method 2: Creating a new file from scratch 


1 


Click the Create icon on the main toolbar; or, if no file is open 
yet, you may click File and then New, as before. 


If a file is already open on screen, a drop down box will appear. 
Choose Create New File from Scratch. 


The same dialog as before will appear, but it will be blank - 
allowing you to input brand new values. 


Start by adding a new Key using the Key menu - or press Ctrl-A. 
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5 Fill in the attributes for the key in the lower section of the dialog. 


6 Continue adding or removing new keys and segments as desired, 
using the menus or right-clicking on the key in the list. 


7 Now click the Create button to execute the B_Create (14) 
operation. This will automatically open the file on screen as well. 
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How to Create Table Definitions for Existing Btrieve Files 


This chapter explains how to make an existing Btrieve data file 
available to relational (SQL or ODBC) applications. 


If you have an existing application that uses the transactional Btrieve 
interface to access data, and you would like to be able to access the 
same data using Pervasive Replication, Microsoft ODBC Bridge for 
ADO, Microsoft Access, or other ODBC-based applications, then 
this chapter provides the information you need. 


This chapter consists of the following sections: 


=» “How to Use this Chapter” on page 12-2 

m “Creating a Database” on page 12-4 

m “Associating a Data File with a Database” on page 12-5 
m “Building a Table Definition” on page 12-7 
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How to Use this Chapter 


Although this chapter is broken into several sections, it is designed to 
be read from front to back sequentially. 





~~ Note Depending on the complexity of your application, this chapter 
may require that you have substantial knowledge of the internal record 
structure of your Btrieve data file. 





Before you Be- Make Sure it’s Necessary 


gin Before you follow the instructions provided in the remainder of this 
chapter, you must determine whether your data file is already 
enabled for ODBC/relational access. 


> To determine whether your data file is ODBC-enabled 


1 Inspect the folder or directory where your Btrieve file is 
currently located. If you see files named FIELD.DDF, FILE.DDE 
and INDEX.DDF in this folder, then most likely your data file 
can already be accessed with ODBC. 


Wow While most applications keep the DDFs in the same directory as 
the data files, storing them in the same location is not required. You 
may wish to search the same physical volume as the data files for one of 
the above mentioned DDF files, to be sure that you do not have DDF 
files available. 








If this is the case, then you need only set up access to the 
database. Follow the instructions provided in Chapter 2 of 
Pervasive.SQL User’s Guide. 


Decide on Your Goal 


Next, you must decide what you want to do. Do you want to build a 
brand new Pervasive.SQL database around an existing Btrieve file (or 
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files), or do you want to add an existing Btrieve file as a new table in 
an existing Pervasive.SQL database? 





If you want to do this ... ... follow these instructions: 





Create a brand new database “Creating a Database” on page 12-4 
around my Btrieve file 





Add your Btrieve file to an existing | “Associating a Data File with a Database” on 
database page 12-5 
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Creating a Database 
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This section explains how to create a new database for one or more 
existing Btrieve files. 


If you wish to add a Btrieve data file to an existing relational 
database, please skip to the next section of this chapter, “Associating 
a Data File with a Database.” 


» To create a new database 


1 


Follow the detailed instructions in Pervasive.SQL User's Guide 
Chapter 2, “Setting Up Database Access.” 


During the above-mentioned procedure, you will be asked to 
specify the location of the database. You should specify the 
location of the existing Btrieve file(s) around which you wish to 
build a database. 


After creating the database, there are three DDF files in the same 
directory as your Btrieve files. These newly created DDFs are 
empty. You must now populate the DDFs with table definitions 
for your existing Btrieve files. The steps that follow will show you 
how to perform this task. Proceed to the next section of this 
chapter, “Associating a Data File with a Database.” 


Associating a Data File with a Database 





Associating a Data File with a Database 


To add a Btrieve data file to a Pervasive.SQL database, you must 
associate the data file with a table definition in the database. 


Ús 





Tip Moving your Btrieve file to the same directory as the other data 
files in the database can make database maintenance tasks easier. Do 
not move the file unless you can re-configure your existing Btrieve 
applications to be aware of the file's new location. 





To create a table definition for a data file 


If you do not have Pervasive Control Center (PCC) open, start it 
now by choosing Start | Programs | Pervasive | Pervasive 
Control Center. 


Double-click Pervasive.SQL 2000i Engines to show a list of 
engines registered with PCC. Next, double-click the icon 
representing your target engine, to show a list of the databases 
serviced by that engine. 


Right click on the database to which you want to add the Btrieve 
file. Choose New | Table. This step brings up the Create Table 
Wizard. 


Figure 12-1 Create Table Wizard—Advanced Settings 


Create Table Wizard for Pervasive SQL 2000i |x] 
Specify how you want to create a table 
You may create a table "from scratch" in the designer window or you may choose 
to create a new table based on an existing Btrieve data file. 


What do you want to name your table? 











Table name: — [person 





Use "advanced settings" if: 


+ You have an existing Btrieve file and you want to create a SOL table using 
this data file. 


+ You are aware of the Btrieve file's intemal structure and know how to deal 
with it properly. 





< Back Cancel | 
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4 


In the Create Table Wizard, enter the name you want to assign to 
the new table and click Use advanced settings, as shown in 
Figure 12-1, “Create Table Wizard —Advanced Settings.” The 
table name must be no more than 20 characters. It does not have 
to correspond to the data file name, although that is a good idea 
to help you remember which file corresponds to which table 
definition. Click Next. 


Figure 12-2 Create Table Wizard —Specify Btrieve File 


Create Table Wizard for Pervasive. SQL 20001 xi 
Specify advanced settings 
If you want to create your table from an existing 
Btrieve data file, specify its location here. 


Specify the location of the Btrieve data file to use to create the SOL table. 


JEAPvSwSbtflestperson.mkd Hj 

















The Wizard will try to investigate the existing Btrieve file in order to get information 
about the existing columns and indexes. 


After that, the Wizard will prompt you to edit the layout found and to define your own 
cams and indexes manually by splitting and merging the columns found by the 
izard. 





< Back Cancel | 





In the next window, specify the Btrieve file for which you are 
creating a table definition. Ifyou don't want to type the path, you 
may click ... to select the file. See Figure 12-2 “Create Table 
Wizard —Specify Btrieve File.” In the example screen, we are 
creating a table definition for the file person. mkd. 


Click Next to display “Columns and Indexes found in the Btrieve 
file” window, as shown in Figure 12-3. 


Your table name is now associated with the data file, but the table 
definition is still empty, except for any index definitions that 
were found. Do not exit the Create Table Wizard. Continue to the 
next section of this chapter, “Building a Table Definition,” for 
detailed instructions on using the remaining screens of the 
wizard to build a table definition for the specified data file. 


Building a Table Definition 





Building a Table Definition 


Determining 
background in- 
formation 


The table definition you have created is “empty”—it does not 
contain any information about the structure of the data file. You 
must now populate the table definition with specific information 
about the record structure of the data file. The Create Table Wizard 
guides you through this task by detecting certain structures within 
the data file, and helping you define the remaining field 
characteristics. 


This section uses the Btrieve file PERSON.MKD as an example. This 
file is provided in the product as part of the “demodata” sample 
database. 


Records in a Btrieve file can consist of any mixture of fixed-length 
and variable-length fields. In the physical file on disk, all the fixed- 
length fields and the pointer values for the variable-length fields are 
stored together. This is called the fixed-length portion of the record. 
The data contained in the variable-length fields is stored at the end 
of the fixed-length portion of the record, as a single large block of 
data. 


You can determine whether the data file has at least one variable- 
length field by obtaining the file statistics on the Btrieve file using the 
Btrieve Maintenance Utility. Pervasive Software offers both a 
command-line and graphical version of the Btrieve Maintenance 
Utility. For the examples in this section, we chose to use the 
command-line Btrieve Maintenance Utility (BUTIL). 


The following is an excerpt of the output produced by running the 
command BUTIL -stat on the PERSON.MKD file. 


Total Number of Records = 1500 

Record Length = 333 

Data Compression = No 

Variable Records = Yes 
Variable-Tail Allocation Tables = No 
Blank Truncation = No 

Free Space Threshold = 5% 


From this output, we can determine that at least one variable-length 
field is defined. From the Record Length specified, we can also 
determine the size of the fixed length portion of the record. You will 
use this information later. 
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Naming Known Btrieve files contain some information about field lengths and data 

Fields types, indexes, and overall record length that must match the 
corresponding table definition. The Create Table Wizard analyzes 
this information to come up with definitions of the indexed fields in 
the file, as shown in Figure 12-3. 


» To name the indexed columns 


1 Continuing the Create Table Wizard steps from the previous 
section, the next window displays the columns and indexes that 
the wizard was able to discover in the file. See Figure 12-3 
“Create Table Wizard —Columns and Indexes Detected.” 





~~ Note In most cases, not all columns are displayed. The wizard can only 
detect columns that have indexes defined on them. This is the only 
method the wizard can use to gain information about the internal 
record structure of the file. As explained in the following steps, you 
must supply most of the information about the record structure. 





Figure 12-3 Create Table Wizard —Columns and Indexes Detected 








Create Table Wizard for Pervasive. SQL 20001 x] 


Columns and indexes found in the Btrieve file 
‘You may view the columns and indexes found in the data file and, using this 
information, define the columns and indexes for the new table. 








Indexes found 
Column name 
ID 


Last_Name 





First_Name 
unnamed _4 
Perm_City 





Columns found 
Column name 

ID unsigned 
First_Name zstring 
Last_Name 

Perm_City 





unnamed_4 zstring 





Name the columns appropriately according to your knowledge 
of the record structure. The maximum length for a column 
name is 20 characters. Click Next when you are finished. 
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maining Col- 
umns 


A 


Building a Table Definition 





Note If you are inspecting a Btrieve file that was created with 
Pervasive.SQL 2000 or later, each column that is allowed to have NULL 
values is preceded by a one-byte space that contains a NULL indicator 
value. You should not explicitly define these spaces as columns, 
however, you must allow for this extra byte when specifying the 
column offset. You should count this space as part of the column. 








Note If you use Btrieve Maintenance Utility to display field data about 
a Btrieve file, you must mentally subtract one (1) from the position 
values shown in Btrieve Maintenance Utility output to generate 
comparable offset values, as shown in the Create Table Wizard. This is 
because byte position one (1) in the record, as shown in Btrieve 
Maintenance Utility, corresponds to an offset of zero (0), as shown in 
the Create Table Wizard. 








Caution If there are any field overlaps in your indexed columns, you 
cannot create a valid table definition for your Btrieve file without 
modifying the file. For example, in the sample definition, you would 
have a field overlap if there were an indexed field at offset 5 with length 
of 1 or more. This would overlap the bytes in the ID field, and possibly 
the First_Name field as well. 


If you have overlapping field definitions and you want to have 
relational access to the data, then you must: 

(1) remove any indexes from your Btrieve file that refer to overlapping 
fields, and 

(2) modify your Btrieve application program logic to reflect the newly 
changed index definitions. 


Typically you must separate the overlapping fields into multiple fields 
that do not overlap, and define an index (or segmented index) on these 
fields. 





» To define the non-indexed columns 


1 


The next screen is shown in Figure 12-4 “Create Table Wizard— 
Specify Columns.” This window shows you both the indexed 
columns as well as the gaps in the record structure that exist 
between the known columns. These gaps are named 
“unnamed_X” and their data type is currently “unknown.” 
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Figure 12-4 Create Table Wizard —Specify Columns 


Columns and indexes found in the Btrieve file 
You may view the columns and indexes found in the data file and, using this 
information, define the columns and indexes for the new table. 





1... | Communic... | PROF Quaglino Qua... | 204 

1... | Accountin... | ASST PROF Bhargava Bui... | 302 

1... | Communic... | ASSOC PROF | Billingsley Buil... | 104 
| | 






























































ID unsigned ubigint 1 8 B (=| 
Dept_Name char char 10 20 Mm Mm 
Designation 

Building Name | char char 50 [25 a E 
‘Room Number | unsigned uinteger 75 4 Oo B 
unnamed_2 unknown N/A 80 8 Mm 





The task now is to define the structure of the data in these 
undefined areas. Each area may contain one or more fields. 


2 In order to determine how to define these areas, you can inspect 
the actual contents of an undefined area by selecting the area and 
clicking the Split button: a 


Figure 12-5 Create Table Wizard—Split Columns 


Split column 






































woo FA a Ol 
uo a eo wool) 
a [6 1010 01 











20020200) 
oOo] ON www 
































9 Ascii 








3 The next window to appear is the Split Column window. This 
window allows you to view the data in an undefined area and 
determine where it should be split into separate fields. 


By default, the window shows hex codes for each byte of data in 
several rows of the data file. Click Ascii view to switch to a view 
that shows the hex codes as ASCII characters. 


Building a Table Definition 


4 Visually inspect the data in the Split Column window to 
determine where fields begin and end. 


5 Click in zero or more Split At checkboxes to specify where the 
additional columns should begin. Keep in mind itis possible that 
the space is all one field, so you may not click any checkboxes. 
See Figure 12-5 for an example. The first field appears to be zip 
code information, while the next field appears to be country 
information. 


Ifyou know that you are defining columns that are nullable, split 
the columns by checking the box immediately prior to where the 
data starts. In the example shown, box 13 is checked because it is 
the null indicator position for the nullable “Country” 
information that begins in the next byte. 


Later, when you go back to the main window, remember to check 
the Null box for this field. Doing so creates the null indicator 
byte corresponding to box 13, and specifies that the actual data 
starts at the next position, as is correct. 


Click OK when you are ready to execute the split and go back to 
the main window. 

6 You may need to visit the Split Column window several times. 
You can also use the Merge button $$ to undo a split, if you 
split a column in the wrong place. You merge two or more 
adjacent columns into a single field by selecting the ones you 
want to merge and clicking the Merge button. 


7 Return to the main window and specify different data types if 
necessary, to achieve the desired display of column data in the 
main window. 


Remember, nullable fields have a one-byte null indicator at the 
beginning of the field. When you click Null to make a field 
nullable, the fields start position increases by one (allowing for 
the null indicator byte) and the field’s length decreases by one 
byte (because the next field must still begin at the appropriate 
location). If you find that you have a number of fields that are off 
by one byte, check that you have the Null attribute set correctly 
for all the columns in question. 


Non-character columns may be difficult to interpret accurately. 
Columns of type BIT and LOGICAL may require a detailed 
knowledge of the record structure to define them properly. 
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If you create a column of type BIT, eight columns are created 
automatically, one for each bit in the byte selected. Ifyou do not 
have eight bit columns to be defined, simply select the extra 
columns and click the Delete button: Es 





Note If you are working through the fields sequentially from front to 
back and you reach a point where the Wizard won't allow you to define 
the columns correctly, you can try a couple other approaches: 

1) Work through the remaining fields from back to front. 

2) Define all the non-indexed fields in a gap area with a single use of 
the Split Column window. Do not define a few of the columns, return 
to the main window, then split again. 





When you are satisfied that your entire column structure is 
correct, click Next in the main window. 


Variable length fields 


Variable-length fields require special mention. These must be 
specified as a blob data type, with a size of 8 bytes. The 8 bytes are 
actually a pointer value into an offset location in the variable-length 
portion of the record that comes after the fixed-length columns. 


The table below summarizes the full contents ofthe PERSON.MKD 
example file, as deduced by the Create Table Wizard: 


Table 12-1 Complete Field Definition for PERSON.MKD file 



































Field Name Position Size Data Type 
Student_ID 1 8 Unsigned 
FirstName 10 16 Zstring 
LastName 27 26 Zstring 
PermStreet 54 31 Zstring 
PermCity 86 31 Zstring 
PermState 118 3 Zstring 
Perm_Zip 122 11 Zstring 
Perm_Country 134 21 Zstring 





Generating a 
Table Definition 


Building a Table Definition 


Table 12-1 Complete Field Definition for PERSON.MKD file continued 















































Field Name Position Size Data Type 
Street 156 31 Zstring 
City 188 31 Zstring 
State 220 3 Zstring 
Zip 224 11 Zstring 
Phone 236 6 Numeric 
EmergencyPhone 243 20 Character 
Unlisted 263 1 Bit 
BirthDate 265 4 Date 
EmailAddress 270 31 Zstring 
Sex 301 1 Logical 
Citizenship 303 21 Zstring 
Survey 324 1 Bit 
Smoker 324 1 Bit 
Married 324 1 Bit 
Children 324 1 Bit 
Disability 324 1 Bit 
Scholarship 324 1 Bit 
Comment 326 8 blob 




















This section explains how to complete the task of creating a table 
definition, once you have finished creating definitions for all the 
columns in your Btrieve file. 


> To complete the task of creating a table definition 


1 After you complete all the field definitions and click Next, a new 
screen appears listing the SQL statement that creates the table 
structure you have defined. See Figure 12-6. Click Save... to save 
the SQL statement to a text file. 
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Figure 12-6 Create Table Wizard —Save SQL Script 


Create Table Wizard for Pervasive.SQL 20001 


Generate SQL Script 


At this stage you can get the SQL script generated on the basis of information that 
you have provided in the previous steps. 


Salary CHAR(8) CASE, 
Building_Name CHAR(25) NOT NULL, 
Room_Number VINTEGER NOT NULL, 


# 


CREATE UNIQUE INDEX index_1 ON faculty(ID # 
CREATE INDEX index_2 ON faculty(Dept_Name W 
CREATE INDEX index_3 ON faculty(Building_Name , Room_Numbe 





It is recommended that you save the statement in case you need 
to reconstruct the table definition later, or in case you want to 
make minor changes to the table definition and then re-create it. 


Click Next. 


Figure 12-7 Create Table Wizard—Finish 
Create Table Wizard for Pervasive.SQL 20001 


Completing Create 
Table Wizard 


You have successfully completed the steps 
necessary to create the table. 


When you click the Finish button, the table will be 
created. 


To create the table, click Finish. 





2 Inthe next screen, you must confirm whether you want the table 
definition to be created, as shown in Figure 12-7. Click Finish. 
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Verifying a Ta- 
ble Definition 


Conclusion 


Building a Table Definition 


You should verify the table definition after generating it. The 
verification process performs two tasks: 


m Verifies that the index definitions in the table match the index 
definitions in the Btrieve file. 


m Verifies that the field definitions match what you expect for your 
data. 


> To verify the database definition 


In PCC, right-click the database to which you have just added 
the table definition, then choose Tasks | Check Database. The 
Check Database Wizard guides you through the steps to check 
your database definitions. 


As you can see, creating a table definition for an existing Btrieve file 
can be a time-consuming, highly detailed task. However, when the 
task is complete, the result is a Btrieve file that can be accessed 
concurrently by both ODBC-based applications and Btrieve 
applications. 
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Handling Btrieve Files with the Maintenance Utility 


This chapter discusses the following topics: 
= “Maintenance Utilities Overview” on page 13-2 
= “Btrieve Interactive Maintenance Utility” on page 13-3 


= “Btrieve Command-Line Maintenance Utility (BUTIL)” on page 
13-32 
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Maintenance Utilities Overview 
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Pervasive.SQL provides both an interactive Maintenance utility and 
a command-line Maintenance utility. Both Maintenance utilities 
perform the following common file and data manipulations: 


= Create new data files based on file and key specifications you 
define. 


= Provide file and key specifications for existing data files. 
= Set and clear owner names for data files. 

= Create and drop indexes on data files. 

= Import and export ASCII sequential data. 

= Copy data between Pervasive.SQL data files. 


m Recover changes made to a file between the time of the last 
backup and a system failure. 


While both utilities provide the same core functionality, minor 
differences exist. For example, the interactive Maintenance utility 
allows you to create description files based on file and key 
specifications you define. The command-line Maintenance utility 
allows you to start and stop continuous operation on a file or set of 
files locally on the server. 


Before you use either Maintenance utility, you should be familiar 
with Btrieve fundamentals, such as files, records, keys, and segments. 
For information about these topics, refer to the Pervasive.SQL 
Programmer’s Guide. 





— Note The Pervasive.SQL product provides two categories of 
maintenance utilities: Btrieve and SQL. The SQL Maintenance Utility 
supports data source names (DSNs), which are used for relational 
access through ODBC. See “Backing Up a Database with SQLUTIL” on 
page 8-18 for a discussion of the SQL Maintenance Utility. 





Btrieve Interactive Maintenance Utility 





Btrieve Interactive Maintenance Utility 


Extended File 
Support 


Long File Name 
Support 


The Interactive Maintenance utility runs on Win16 (client/server 
only), and Win32 (Pervasive.SQL client/server and workstation 
products). Use this utility if you prefer a graphical interface or if you 
want to create a description file. This section contains the following 
major topics: 

m “File Information Editor” on page 13-7 

= “Owner Names” on page 13-20 

m “Statistics Report” on page 13-22 

m “Indexes” on page 13-24 

= “Data” on page 13-27 


Each major topic contains tasks specific to that topic. 


The size of a MicroKernel data file can be larger than the operating 
system file size limit. When you export data from an extended 
MicroKernel file to an unformatted file, the size of the unformatted 
file can exceed the MicroKernel file size limit because of the 
differences in the physical format. 


The Interactive Maintenance utility detects that the unformatted file 
has exceeded the file size limit (2 GB) and starts creating extension 
files. This process is transparent. Extension files and the original 
unformatted file must reside on the same volume. The extension file 
uses a naming scheme in which the file names are similar to the base 
file name. The first extension file is the same base file name with 
“AOL extension. The second extension file is ‘402, and so on. These 
numbers are printed in hex. While the naming convention supports 
up to 255 extension files, the current maximum number of extension 
files is 32. The maximum file size is dependent on the page size. The 
maximum number of pages is 16 million. Ifyour page size is 4096 
bytes, then the file can grow to 64 GB. If your page size is 512 bytes, 
then the maximum file size is 8 GB. 


Additionally, when you import data from an unformatted file, the 
utility detects if the file has extensions and loads the data from the 
extension file. 


Long file name support, including support for embedded spaces, has 
been added in the Pervasive.SQL Service Pack 3 for both the NetWare 
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The Btrieve 
Maintenance 


and Windows 32 environments. All references to files can contain 
embedded spaces and be longer than 8 bytes. 


Previous versions of Btrieve allowed spaces to be added at the end of 
a file name in path-based operations such as Open and Create. This 
is still the default behavior. Existing applications will not break. 
However, if you want to take advantage of file and directory names 
with embedded spaces, change the Embedded Spaces setting for the 
Btrieve Requester to “Yes.” In the registry, you can locate this setting 
under: 


HKEY_LOCAL_MACHINE\SOFTWARE\Pervasive 
Software\BtrieveRequester\Version 7.0\Settings\Embedded Spaces. 


Even when you turn the option “Off,” an application that accesses a 
file having a name with embedded spaces can enclose that name in 
double quotes while making the BTRV/BTRVID/BTRCALL/ 
BTRCALLID call to open or create the file. 





Note On NetWare, long file name support is available only in the 
MicroKernel and not in any of the other NLM utilities such as 
BUTIL.NLM. This means that Btrieve data files may be accessed using 
long names but long names cannot be used for any other kind of files. 
For example, in the NLM command: 


BUTIL -CREATE <outputFile> <descriptionFile> 
The <outputFile> being a Btrieve data file manipulated by the MKDE 


can have along name but the <descriptionFile> must have only a short 
name as BUTIL.NLM does not understand long names. 





You start the Btrieve Maintenance Utility by clicking Start | 
Programs | Pervasive.SQL 2000i | Utilities | Maintenance. The 


Utility Interface utility’s main window displays as illustrated in Figure 13-1. 
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Figure 13-1 Btrieve Maintenance Utility Main Window 


Btrieve Maintenance Utility 


Options Index Data Help 





Menu Options 


The interactive Maintenance utility provides the following menus: 


Options Allows you to display the File Information Editor, set and clear owner 
names, generate statistics reports, and exit the utility. 


Index Allows you to create and drop indexes. 

Data Allows you to load data from ASCII files, save data to ASCII files, copy 
records between data files, and perform a roll forward operation to 
recover changes made to a data file between the time of the last backup 
and a system failure. 


Help Provides access to the Maintenance utility help system. 


Getting Help 


To access the Maintenance utility help system, choose a command 
from the Help menu, as follows: 


Getting Help Explains how to use the Maintenance utility help system. 


Index Provides a list of Maintenance utility help topics. 
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Help on Help Explains how to use the help system. 
About Displays copyright information and the version number. It also 


provides the version number of the MicroKernel Database 
Engine and Btrieve client Requester, if they are loaded. 


In addition, you can display help for a particular dialog box by 
clicking the Help button contained in that dialog box. 


13-6 


File Information Editor 





File Information Editor 


This section provides general information about the File 
Information Editor with which you can create new files based on file 
and key specifications you construct. Because this Editor allows you 
to load information based on an existing file, it is also useful for 
viewing file and key specifications on existing data files. You can also 
create a new file based on the file and key specifications ofan existing 
file (similar to CLONE in the command-line Maintenance utility on 


page 13-47). 


You open the File Information Editor by clicking Options | Show 


Information Editor. 


Figure 13-2 File Information Editor 























E File Information Editor |x| 
Set To Defaults | Data File Info 
— Owner Name: 
Create File... Description comments... | T N/A 
Help Total Records: N/A 
File Specification 
Record Length Available Linked Keys B | I~ Data Compression 
Page Size 4096 y] I Key-Only I Variable Records 
7 Balanced Indexing F Blank Truncation 
# Keys: o | [I Pre-allocation [Include VATs 
# Segments: o | # Pages % kee Space [5 EI 
Key Key Segment f Key, Segment 

J Duplicates Data Type} String H 
Ll Modifiable a Position [o] 
F Repeating Duplicates 
F Null Key Length [o] 

€ All Segments (Null) Hull Value [Hex] fe | 

© Any Segment [Manual] Es I Case Insensitive 

AGS Information | Delete F Descending 

Unique Values: N/A Compress [Use AUS 























File Information At the top of the Editor, the following buttons appear: 


Editor Dialog 
Elements 


Load Information 


Loads information based on an existing file. When you load 


information, you are not editing the existing file. Instead, you 
are loading a copy of the information about that file. 


Create File 
box. 


Set to Defaults 


Sets the controls to default values. 


Creates a new file based on current information in the dialog 
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Description 
Comments 


Show 6.x 
Attributes 


Help 


If you are creating a description file, allows you to enter notes 
about the file. 


Displays controls specific to 6.x and later files, which are 
unavailable when you load information based on a pre-6.0 
file. (This button is unavailable unless you load information 
based on a pre-6.x file.) 


Displays help for the File Information Editor dialog box. 


The Data File Info box, also at the top of the File Information Editor, 
contains the following controls: 


Owner Name 


Version 


Total Records 


Provides a text box you can use to specify the owner name, 
if applicable, for an existing file. 


Earliest version of the MicroKernel that can read all the 
attributes of the file. For example, if you created a file using 
the 6.15 MicroKernel but did not use any attributes specific to 
6.15, the Maintenance utility displays 6.0 as the version 
number. See “File Version Notes” on page 13-60 for 
additional information about file format versions. 


Total number of records in the file. 


The File Specification box is in the middle of the File Information 
Editor. Table 13-1 describes the controls in this box. 


Table 13-1 File Specification Controls 





Control 


Description Range Default 





Record 
Length 


Specifies the logical data record length | 4-4,088 100 
(in bytes) of the fixed-length records ina 
file. 





Page Size 


Specifies the physical page size (in 512- 4,096 
bytes) for the file. 4,096 





# Keys 


Indicates the number of distinct keys (as | 0-119 0 
opposed to key segments) currently 
defined in the Editor. Reflects the 
number of keys in the Key list. 





# Segments 











Indicates the number of key segments | 0-119 0 
currently defined in the Editor. Reflects 
the number of segments in the Segment 
list. 











Table 13-1 File Specification Controls continued 


File Information Editor 





Control 


Description 


Range 


Default 





Available 
Linked Keys 


Specifies how many 8-byte place 
holders you want to reserve for future 
linked-duplicatable keys. If you are 
loading information based on an 
existing data file, this value reflects the 
number of place holders currently 
available in that file. (The number of 
originally reserved place holders is not 
stored in the file.) 


0-119 


3 





Key-Only 


Indicates whether the file is key-only. 
Not applicable if you turn Data 
Compression on, if you turn Variable 
Records on, or if you define more than 
one key for the file. 


On or Off 


Off 





Balanced 
Indexing 


Pre- 
allocation 


# Pages 


Specifies that the file uses the balanced 
indexing method of managing key 
pages. 


Specifies that the file uses preallocated 
pages. 


Specifies the number of pages you want 
preallocated when you create the file. 
Applicable only if Pre-allocation is 
turned on. If you are loading information 
based on an existing data file, this value 
reflects the number of unused, 
preallocated pages left in that file. (The 
number of originally preallocated pages 
is not stored in the file.) 


On or Off 


On or Off 


1-65,535 


Off 


Off 





Data 
Compression 


Specifies that the file uses data 
compression. Not applicable for key- 
only files or files that use blank 
truncation. 


On or Off 


Off 





Variable 
Records 


Specifies that the file can contain 
variable-length records. 


On or Off 


Off 





Blank 
Truncation 








Specifies whether the file uses blank 
truncation on variable records to 
conserve disk space. Applicable only if 
Variable Records is turned on. 





On or Off 





Off 
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Table 13-1 File Specification Controls continued 





Control Description Range Default 





Include VATs | Specifies whether the file supports On or Off | Off 
Variable-tail Allocation Tables for faster 
access to data in very long records. 
Applicable only if Variable Records is 





turned on. 
% Free Specifies the amount of unused spacea | 5, 10,20, |5 
Space file's variable pages must have available | or 30 


before the MicroKernel creates a new 
variable page. Applicable only if Data 
Compression or Variable Records are 
turned on. 




















At the bottom middle of the dialog box, the Key list shows the key 
numbers defined in a file. (For 6.x and later files, these key numbers 
do not have to be consecutive; they can have gaps between them.) 
The Maintenance utility displays the highlighted key's specifications 
in the Key box at the bottom left of the dialog box. 


Also at the bottom middle of the dialog box, the Segment list shows 
the key segment numbers defined for the key highlighted in the Key 
list. The Maintenance utility displays the highlighted segment's 
specifications in the Segment box at the bottom right of the dialog 
box. 


In addition, the following buttons appear under the Key and 
Segment lists: 


Insert Defines a new key or segment. 
Delete Removes the highlighted key or segment specification. 
Compress Renumbers the keys consecutively. You can use this button to 


remove gaps that result from deleting a key specification. 





Note Because these buttons control key specifications for a file you 
want to create, you cannot use them to operate on keys in an existing 
file. If you want to create or drop an index on an existing file, refer to 
“Index Tasks” on page 13-24. 





File Information Editor 


At the bottom left in the dialog box is the Key group box. Table 13-2 
describes the controls in this area. These controls are specific to the 
designated key (that is, the key highlighted in the Key list), not just 
to the current key segment. When you change the setting for one of 
these controls, the change affects all segments of the specified key. 


Table 13-2 Key Specification Controls 














Control Description Default 

Duplicates Specifies that the key can have duplicate values. On 

Modifiable Specifies that the key value can be modified after On 
creation. 

Repeating Specifies that the MicroKernel uses the repeating- Off 


Duplicates duplicatable method of storing duplicate key values. 





Sparse Key A sparse key does not contain a key value for each Off 
record in the file. The records with NULL values for the 
indexed field are not included in the index. Key flag 
0x0200 is used for this purpose. 





Null Key Specifies that the key has a null value. Off 





AllSegments | Specifies that if all key segments in the record contain | Off 








(Null) the null value, the MicroKernel does not include that 

record in the key path. Applicable only if Null Key is 

turned on. 
Any Specifies that if one or more key segments contain the | Off 
Segment null value, the MicroKernel does not include that record 
(Manual) in the key path. Applicable only if Null Key is turned on. 
ACS Allows you to specify an alternate collating sequence | Off 


Information (ACS) for the key. Applicable only if the Use ACS check 
box is selected for a segment of the key. 





Unique Indicates the number of unique key values in the file. N/A 
Values Applicable only if you are loading information based on 
an existing data file. 

















At the bottom right in the dialog box is the Key Segment group box. 
Table 13-3 describes the controls in this area. These controls are 
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specific to the designated key segment (that is, the segment 
highlighted in the Segment list), 


Table 13-3 Key Segment Specification Controls 





Control Description Default 





Data Type Specifies a data type for the key segment. String 


The NULL data type indicates that the index is one 
byte Null indicator segment. It must be in a multi- 
segment key and it must precede another key 
segment that is not a NULL type. The number used in 
the Btrieve API for this key type is 255. 





Position Specifies by number the relative starting position of 1 
the beginning of this key segment in the record. The 
value cannot exceed the record length. 





Length Specifies the length (in bytes) of the key segment. This | 10 
value cannot exceed the limit dictated by the data type 
for the segment. The total of key position and key 
length cannot exceed the record length. 





Null Value Specifies the null character value (in hexadecimal) for | Binary 
the key segment. Applicable only if the Null Key check | zero 
box is selected for the key. 





Case Specifies whether the segment is sensitive to case. On 
Insensitive Applicable only for STRING, LSTRING, and ZSTRING 
data types or for keys that do not use an ACS. 





Descending Specifies that the MicroKernel sort the key segment Off 
values in descending order (that is, from highest to 
lowest). 





Use ACS Specifies that the segment uses the alternate collating | Off 
sequence defined for the key. Applicable only for 
string, lstring and zstring data types that are 
case sensitive. 





Null Value NULL Value Discrete Ordering is used for the null Off 
Discrete indicator segment (NIS) to determine whether the 
Ordering MKDE should treat the NIS as a boolean value, where 


any non-zero value is considered NULL, or as a one 
byte integer, where zero is considered non-null and all 
other values are considered different types of null. In 
this case they are sorted as discrete values. The 
Btrieve API uses the NO_CASE flag, 0x0400, to 
indicate discrete ordering should be performed, 
because that flag was previously unused for integer 
values. 
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Information Ed- You perform the following tasks with the File Information Editor: 


itor Tasks 


= Load information from an existing data file (page 13-13) 
= Create a new file (page 13-14) 

= Compact a Btrieve file (page 13-16) 

= Show or hide 6.x data (page 13-17) 

= Specify a key's alternate collating sequence (page 13-18) 


Loading Information from an Existing Data File 


When you load information from an existing file, you are not editing 
the existing file. Instead, you are loading a copy of the information 
about that file. Generally, you want to load a data file before 
performing other tasks with the File Information Editor, but this is 
not mandatory. 


> To load information from an existing data file into the 
File Information Editor 

1 Click Load Information at the top of the File Information 
Editor. The Select File dialog box appears (Figure 13-3). 


Figure 13-3 Select File Dialog Box 








Select File 












[S] Dbu_uidll O Inssct hip 


[S] Sqlutil dil 





B] Butilres. dll laa] Ddftool.cnt ge Iscoutl6.exe E Sqlutil. exe 
a] Cmdiag16.dll AL) Ddftool.exe ga Iscout32.exe z Sscout exe 
9] Cmdiag32.dll @ Dditoolhip [S] Psapi dll @Sscouthip 
laa] Code_msg.cnt 3] Gx6050r. dll A Sqlscope.exe [a] Sscout32.ı 


> 
Fiename: | 
Files of type: | All Files (2) pr Cancel | 


2 Specify the name and path of the file for which you want to load 


information. (By default, data files have a . mkd extension.) 


The Maintenance utility first attempts to open the specified file 
as a data file. If the file requires an owner name, the utility 
prompts you for one. (Because owner names are optional, the 
file you open may not require an owner name.) If the specified 
file is not a data file, the utility then attempts to open the file as 
a description file. 
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Creating a New File 


You can create a new file based on the current information in the File 
Information Editor or on new information you provide. 


» To create a new file based on the current information 
in the File Information Editor 


1 Click Create File at the top of the File Information Editor dialog 
box. The Create File dialog box (Figure 13-4) appears. 


Figure 13-4 Create File Dialog Box 


File Name 





tt 








m File Type 
@ MicroKernel-compatible 
C Description 
F Index Only 








System Data 
@ Use engine setting 
No system data 

€ Force system data 











Lx] 
Cancel | 
Help | 





File Information Editor 


2 Specify the controls in the Create File dialog box, which are 
described in Table 13-4. 


Table 13-4 Create File Dialog Controls 




















Setting, the utility uses the setting for the 
System Data configuration option described 
on page 4-11. If you choose No System Data, 
the utility does not create system data, 
regardless of the engine configuration. If you 
choose Force System Data, the utility creates 
system data, regardless of the engine 
configuration. 


This is applicable only if the file type is 
MicroKernel-compatible. 





Control Description Default 
File Name | Specifies a name and path for the file. By N/A 
default, data files have a . mkd extension. 
File Type Specifies the type of file to create. If you are MicroKernel- 
creating a description file, you can use the compatible 
Index Only option, which creates a description 
file you can use with the BUTIL utility to add an 
index to an existing data file. (For more 
information, referto “Creating Indexes” on page 
13-24.) 
System Determines whether the utility includes system | Use Engine 
Data data in the file. If you choose Use Engine Setting 








Adding Comments to a Description File 


The comments are written to the top of the description file when you 
create the description file. For example, the comment, “This is my 
file,” appears at the top of the description files as /+ This is my 
file */. Ifyou add additional comments after creating the 
description file, you need to create the file again to include the 
additional comments. 


> To add comments to a description file 


1 Click Description Comments. The Description File Comments 
dialog box (Figure 13-5) appears. 
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Figure 13-5 Description File Comments Dialog Box 


Æ Description File Comments x| 


a 





2 Entera block of comments up to 5,120 characters long. 


3 Click OK when you are finished entering comments. 


Compacting Btrieve Data Files 


You can compact a Btrieve data file to remove unused space in it, 
which ultimately decreases the file's size. You can also perform this 
procedure using the command-line Maintenance utility (page 13- 
56). 


> To compact a Btrieve file 


1 Click Load Information in the File Information Editor and 
select the file you want to compact. 


2 Click Create File, give the file a new name (which creates a clone) 
in the Create File dialog box, and click OK. 


3 From the Data menu on the main window, select Save. In the 
Save Data dialog box, enter the name of the original file in the 
From MicroKernel File box and then specify a name for the 
output file (for example, <original file>.out) in the To 
Sequential File box. 


4 Click Execute. The Save Data dialog box displays the results of 
the save. Click Close. 


5 From the Data menu, select Load. In the Load Data dialog box, 
enter the name of the sequential data file you just saved in the 
From Sequential File box. Then enter the name of the clone file 
you created in Step 2 in the To MicroKernel File box. 


File Information Editor 


6 Click Execute. The Loading Data dialog box displays the results 
of the load. Click Close. 


You can now compare the size of the original file to the clone file 
to verify the reduction in size. 


Showing and Hiding 6.x Data 


When you load a pre-6.0 file, all the controls in the File Information 
Editor that are specific to 6.x and later are unavailable unless you 
click the Show 6.x Data button. For example, one feature that is 
specific to 6.x and later is the use of variable-tail allocation tables, or 
VATs. 


This button is useful for users working in environments that use 
both pre-6.0 and 6.x and later MicroKernels. By hiding the 6.x- 
specific controls, you can avoid unintentionally creating a 6.x file. 
(Pre-6.0 MicroKernels cannot access 6.x files.) 


»> To display the 6.x-specific controls 
= Click Show 6.x Data. 


The Show 6.x Data button is unavailable unless you are working 
with pre-6.0 files. 


Specifying a Key’s Alternate Collating Sequence 


You can use an alternate collating sequence (ACS) to sort string keys 
(types STRING, LSTRING, and ZSTRING) differently from the 
standard ASCII collating sequence. By using one or more ACSs, you 
can sort keys as follows: 


= By your own user-defined sorting order, which may require a 
sorting sequence that mixes alphanumeric characters (A-Z, a-z, 
and 0-9) with non-alphanumeric characters (such as #). 


= By an international sorting rule (ISR) that accommodates 
language-specific collations, including multi-byte collating 
elements, diacritics, and character expansions and contractions. 


Files can have a different ACS for each key in the file, but only one 
ACS per key. Therefore, if the key is segmented, each segment must 
use either the key’s specified ACS or no ACS at all. For a file in which 
a key has an ACS designated for some segments but not for others, 
Btrieve sorts only the segments that specify the ACS. 
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The ISR tables are provided with Pervasive.SQL and are based on 
ISO-standard locale tables. ISR tables are stored in the 
COLLATE.CFG file, which is a Pervasive.SQL system file. This means 
that multiple data files can share a single ISR. 


» To specify a key's alternate collating sequence 
1 Click ACS Information. 


The Maintenance utility displays the Specify ACS Information 
dialog box (Figure 13-6). 


Figure 13-6 Specify ACS Information Dialog Box 


ii Specify ACS Information x] 


C ACS Country/Code 
Country ID 1 

















Code Page |-1 


C ACS File 








coca | un] 


2 You can specify either a country ID and code page, an ACS file 
name, or an International Sorting Rule (ISR) as follows: 








Table 13-5 ACS Information Controls 











Control Description Defau 
lt 

ACS Country/Code 

Country ID An Intel-format number that identifies your -1 


country. Refer to your operating system's 
documentation for specific information. 





Code Page An Intel-format number that identifies the code -1 
page you want to use. Refer to your operating 
system's documentation for specific information. 
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Table 13-5 ACS Information Controls 




















Control Description Defau 
lt 

ACS File Specifies the fully qualified file name of the N/A 
alternate collating sequence file. 

International When you click this radio button you can specify a 

Sorting Rule specific ISR table for sorting international data. 
Pervasive.SQL provides a set of pre-generated 
ISR tables, which are listed in the Pervasive. SQL 
Programmer's Guide. 


3 When you specify a country ID and code page ID, the 


MicroKernel stores the locale-specific collating sequence in the 
data file. Moreover, the MicroKernel can insert new key values 
correctly, even if the locale changes. 


When you specify an ACS file name for a data file, the 
MicroKernel copies the contents of the ACS file into the data file. 
(That is, the data file does not contain the file name of the ACS 
file.) The ACS identifies itself using an eight-digit name (such as 
UPPER). Subsequently, when you view the ACS information for 
a data file, the Maintenance utility displays this eight-digit name, 
not the file name of the original ACS. 


When you specify an ACS file name for a description file, the 
Maintenance utility copies the actual path and file name of the 
ACS file into the description file. Subsequently, when you view 
the ACS information for a description file, the Maintenance 
utility attempts to locate the specified ACS file. 


To specify an ACS that sorts string values using an ISO-defined, 
language-specific collating sequence, you must specify an ISR 
table name. The Table Name field is limited to 16 characters. For 
more information on ISRs, refer to the Pervasive.SQL 
Programmer’s Guide, available with the Pervasive.SQL Software 
Developer’s Kit (SDK). 
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Owner Names 


For more information on 
owner names, see “Owner 
Names” on page 7-2. 


Owner Names 
Tasks 
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The MicroKernel allows you to restrict access to files by specifying an 
owner name. Because owner names are optional, the files you use 
with the utility may or may not require an owner name. Owner 
names are case-sensitive. 


Conceptually, owner names are like passwords. They are not the 
same as user or group names, which you can set in the PCC. For 
example, an owner name of “Master” is not the same as the default 
user Master. 

With relational access, an ODBC error results if you attempt to 
manipulate a table that is restricted by an owner name. (For example 
in the PCC, if you double-click the table name or attempt to delete 
the table.) You can use the GRANT statement to grant access to a 
particular user or group, and then manipulate the table via relational 
access through ODBC. The Master user must supply the GRANT 
statement with the correct owner name. 


You perform the following tasks pertaining to owner names: 


= Set or clear an owner name (page 13-20) 


Setting or Clearing an Owner Name 

You set an owner name to restrict access to a file. You clear an owner 
name to remove the access restriction. 

» To set or clear an owner name 


1 Click Options | Set - Clear Owner from the menu on the main 
window. The Set - Clear Owner Name dialog box appears 
(Figure 13-7). 


Owner Names 


Figure 13-7 Set/Clear Owner Name Dialog Box 


E Set / Clear Owner Name x| 


—MicroKernel File 


[_]} Browse. | 


C Clear Owner 


Garrent Owner [| 


@ Set Owner 


New Owner [| 


I Permit read-only access without an owner name. 
F Encrypt data in file. 























mes | | 





In the MicroKernel File box, specify the file for which you want 
to set or clear an owner name. Then, to clear the owner name, 
click Clear Owner and specify the file's owner name in the 
Current Owner box. 


To set the owner name, click Set Owner and specify the file’s new 
owner name in the New Owner box. Select the Permit read-only 
access without an owner name check box to allow anyone to 
read-only access to the records. 


Select the Encrypt data in file check box to ensure that 
unauthorized users do not examine your data using a debugger 
or a file dump utility. Only select this option if data security is 
important to your environment as this requires additional 
processing time. 
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Statistics Report 


Statistics Re- 
port Tasks 
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Generating a statistics report is a good way to determine whether a 
file can be logged by the MicroKernel's transaction durability 
feature. The report shows whether the file has system data and ifa 
key is unique. (A unique key lacks the “D” flag, which indicates that 
duplicates are allowed.) The statistics report provides metadata 
about the file. This information can be used when you troubleshoot 
problems or to help you create similar files. 


You perform the following tasks pertaining to owner names: 


= Create a statistics report (page 13-22) 


» To create a statistics report for an existing data file 


1 Click Options | Create Stat Report from the menu on the main 
window. The Maintenance utility displays the Statistics Report 
dialog box (Figure 13-8). 


Figure 13-8 Statistics Report Dialog Box 


E Statistics Report x| 


Data File: | | Browse | 
Beport File: [ | Browse... | 


I View Report 





cme | uo | 





2 Specify a data file to use and a report file name. If you want to 
view the report when it is created, select the View Report check 
box. 


Ifyou choose to view the report, the Maintenance utility displays 
the View File window as shown in Figure 13-9. 


Statistics Report 


Figure 13-9 Statistics Report Example 


ipyswidemodatalrandom.mkd 


for cipvswidemodatalclass.mkd 


File Version = 7.00 
Page Size = 4096 

Page Preallocation = No 
Key Only = No 
Extended = No 


¡Total Number of Records = 211 


Record Length = 66 
Data Compression = No 
Variable Records = No 


¡Available Linked Duplicate Keys = 0 


System Data = Yes 
SYSKEY Status = Present 





The informational headings in a status report correspond to the 
controls in the File Information Editor, which is described in 
“File Information Editor” on page 13-7. 


The legend at the bottom of the statistics report explains the 
symbols used in the key/segment portion of the report. This 
information includes items such as the number of keys and key 
segments, the position ofthe key in the file, and the length ofthe 
key: 


Legend: 


= Descending Order 

= Duplicates Allowed 

= Case Insensitive 

= Modifiable 

Repeat Duplicate 

= Any Segment (Manual) 

= All Segments (Null) 

= The values in this column are hexadecimal. 
? = Unknown 

-- = Not Specified 


vt Ppa eHoa 
Il 
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Indexes 


An index is a structure that sorts all the key values for a specific key. 
Btrieve access permits overlapping indexes (an index that includes a 
partial column). Relational access through ODBC does not permit 

overlapping indexes. (You can create an overlapping index with the 
File Information Editor, which you can display by clicking the Goto 
Editor button.) 


Index Tasks You perform the following tasks pertaining to indexes: 


= Create an index (page 13-24) 
= Drop an index (page 13-26) 


Creating Indexes 


You cannot create an index for a file unless the file has at least one key 
defined. You can create a key with the File Information Editor (page 
13-7). 

» To create an index 

1 Click Index | Create from the main menu, which opens the 


Create Index dialog box (Figure 13-10). 


Figure 13-10 Create Index Dialog Box 
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Editor To Use Data File 
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2 Complete the following data boxes in the Create Index dialog 
box. 
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Index Type 


Indexes 





Specify whether to create an internal or 
external index. Internal indexes are 
dynamically maintained as part of the data 
file. External indexes are separate files you 
generate as needed. 


An external index file is a standard data file 
that contains records sorted by the key you 
specify. Each record consists of the following: 


@ A 4-byte address identifying the physical 
position of the record in the original data 
file 


@ A key value 





Data File 


Specify the name of the data file for which you 
want to create the index. 





External Index File 


Specify the name of the file to generate for an 
external index. Not applicable for internal 
indexes. 





Key Specification Number in 
Information Editor to Use 


Lists the key numbers defined in the File 
Information Editor. If the file contains a 
system-defined log key (also called system 
data) but the key has been dropped, this list 
includes SYSKEY, which you can select to re- 
add the system-defined log key to the file. 





Existing Key Numbers in Data File 


Click Refresh Lists to display the key number 
defined for the file. If the file contains a 
system-defined log key, this list includes 
SYSKEY. 








Key Number to Use For Create 





Click Refresh Lists to display the key 
numbers available (that is, not defined for the 
file). Highlight the key number you want to use 
when creating the index. 








You can click Go To Editor to display the File Information 


Editor dialog box, which shows more complete information 
about the key. You can click Refresh Lists to read key 
information from the data file and refresh the Existing Key 
Numbers in Data File and Key Number to Use For Create lists. 
You must click Refresh Lists before you can create an index. 


When you have completed the Create Index dialog box, click 


Execute to create the index. The amount of time required to 
create the index depends on how much data the file contains. 
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Dropping Indexes 


Ensure that you understand the access performed by an application 
program before dropping an index. Certain functions fail (such as 
GET NEXT) if a required index is missing. This can result in an 
application program not functioning correctly. 


» To drop an index 


1 Click Index | Drop from the main menu The Drop Index dialog 
box appears (Figure 13-11). 


Figure 13-11 Drop Index Dialog Box 









E Drop Index x| 





Existing Key 
Numbers I Renumber Keys 














2 Complete the following data boxes in the Drop Index dialog box. 





MicroKernel File Specify the name of the data file from which you 
want to drop the index. 





Existing Key Numbers Click Refresh List to display the key number defined 
for the file. Highlight the number of the key whose 
index you want to drop. If the file contains a system- 
defined log key, this list includes SYSKEY, which you 
can select to drop the system-defined log key from 
the file. 





Renumber Keys Renumbers the keys consecutively. Click this button 
to remove gaps that result from deleting an index. 











3 Click Refresh List to get the key information from the file you 
have specified. 
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Data 


Importing and 
Exporting 
ASCII File For- 
mat 


The commands in the Data menu allow you to import, export, and 
copy records in data files. You can also recover data after a system 
failure with the Roll Forward feature. See “Roll Forward Command” 
on page 8-8 for a discussion of Roll Forward. 


When you save data, records in the ASCII file have the following 
format. You can use an ASCII text editor to create files that you can 
load, as long as they adhere to these specifications. Note that most 
text editors do not support editing binary data. 


= The first field is a left-adjusted integer (in ASCII) that specifies 
the length of the record. (When calculating this value, ignore the 
carriage return/line feed that terminates each line.) The value in 
this first field matches the record length specified in the data file. 


+ For files with fixed-length records, the length you specify 
should equal the record length of the data file. 


+ For files with variable-length records, the length you specify 
must be at least as long as the fixed-record length of the data 
file. 


=m A separator (a comma or a blank) follows the length field. 


m The record data follows the separator. The length of the data is 
the exact number of bytes specified by the length field. If you are 
creating an import ASCII file using a text editor, pad each record 
with blank spaces as necessary to fill the record to the 
appropriate length. 

= Acarriage return/line feed (ODOA hexadecimal) terminates each 
line. The Maintenance utility does not insert the carriage return/ 
line feed into the data file. 

= The last line in the file must be the end-of-file character 
(CTRL+Z or 1A hexadecimal). Most text editors automatically 
insert this character at the end ofa file. 


Figure 13-12 shows the correct format for records in the input ASCII 
file. For this example, the data file has a defined record length of 40 
bytes. 
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Data Tasks 
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Figure 13-12 Format for Records in Input Sequential Files 





40, The record follows the comma delimiter <CR/LF> 


Data | 


Carriage Return 
or Line Feed 


Comma Delimiter 
Blank Pad 


Record Length for Proper Length 








You perform the following tasks pertaining to data: 


Import (Load) data records (page 13-24) 
Export (Save) data records (page 13-26) 


Copy data records from one MicroKernel file to another (page 
13-26) 

Recover (Roll Forward) changes made to a data file between the 
time of the last backup and a system failure. See the “Backup and 
Restore” chapter on page 8-1. 


Importing Records From an ASCII File 


You can use the Maintenance utility to import records from an ASCII 
file to a standard data file. This operation does not perform any 
conversions on the data. You can create an import file using a text 
editor or the Maintenance utility (see “Exporting Records to an 
ASCII File” on page 13-29). 


> To import ASCII data 


1 


Click Data | Load from the main menu. The Load dialog box 
appears (Figure 13-13). 


Figure 13-13 Load Dialog Box 


il Load Dialog Lx] 


From Sequential File: {Cid Browse | 
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Data 


The ASCII file you specify must adhere to the specifications 
explained in “Importing Records From an ASCII File” on page 
13-28. The record length of the standard data file you specify 
must be compatible with the records in the ASCH file. 


2 Click Execute to import the records. 


While importing data, the Maintenance utility shows the 
number of records being imported, the percentage of records 
imported, and a status message. You can continue working in the 
Maintenance utility (for example, you can open another Load 
dialog box). 


Exporting Records to an ASCIl File 


You can use the Maintenance utility to export records from a data file 
to an ASCII file. 


> To export ASCII records 


1 Click Data | Save from the main menu. The Save Data dialog box 
appears (Figure 13-14). 


Figure 13-14 Save Data Dialog Box 





i Save Data 
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External Index Fle: 
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2 Inthe Save Data dialog box, specify the following options. 





From MicroKernel File 


Specifies the name of the existing MicroKernel- 
compatible file you want to save. 





To Sequential File 


Specifies the name of the sequential file to create. 





Use An Index 


Uses a specified index when sorting the records for 
export. By default, the Maintenance utility does not 
use an index, meaning that records are exported 
according to their physical position in the data file. 





Internal Index #: 

Uses the specified key number. Click Refresh Index 
List to update the available indexes if you change file 
in the From MicroKernel File box. 





Direction 











External Index File: 

Uses the specified external index. (To create an 
external index, refer to “Creating Indexes” on page 
13-24.) 


Forward: This is the default setting and indicates the 
utility recovers the file from the beginning. 


Backward: This option recovers data from the end of 
the file. 


Forward and Backward: This option reads the file 
forward until it fails. Then it starts at the end of the file 
and reads the file backward until it reaches the 
record that failed previously or encounters another 
failure. 


Backward and Forward: Indicates the utility reads the 
file backward until it fails. Then it starts at the 
beginning of the file and reads the file forward until it 
reaches the record that failed previously or 
encounters another failure. 


3 Click Execute to export the data. The Maintenance utility creates 
the specified ASCII file using the format described in 
“Importing Records From an ASCII File” on page 13-28. You can 
then edit the ASCII file and use the Load command to import 
the edited text to another standard data file, as described in 
“Importing Records From an ASCII File” on page 13-28. 
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Data 


Copying Records Between Data Files 


You can use the Maintenance utility to copy data from one 
Microkernel data file to another. The record lengths for both data 
files you specify must be the same. 


» To copy data 


1 Click Data | Copy from the main menu. The Copy Data dialog 
box appears (Figure 13-15). 


Figure 13-15 Copy Data Dialog Box 
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Bon icokeme ie: [2] omo. | 
coet | _ tow | 


2 Enter the name of the file you want to copy in the From 
MicroKernel File box and then specify the path where you want 
to copy the file in the To MicroKernel File box. 





The record lengths for both data files you specify must be the 


same. 


Recovering (Roll Forward) Changes to a Data File 


See the “Backup and Restore” chapter on page 8-1. 
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Commands 
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Use this utility if you prefer a command-line interface or ifyou want 
to start or stop continuous operation. The Btrieve Maintenance 
utility is also available in a command-line format that runs on the 
server (as an NLM on NetWare or from a DOS command prompt on 
Windows NT) or locally on DOS, and Win32 clients. You can execute 
Maintenance utility commands from the command line or through 
a command file you create. Before you perform commands in the 
Btrieve Maintenance utility, also referred to as BUTIL, itisimportant 
you understand some concepts and elements addressed in the 
Commands. 


The Btrieve Command-Line Maintenance utility performs the 

following common file and data manipulations: 

m “Importing and Exporting Data” on page 13-39 

m “Creating and Modifying Data Files” on page 13-47 

= “Viewing Data File Statistics” on page 13-58 

= “Displaying Btrieve Interface Module Version” on page 13-62 

=» “Unloading the Btrieve Interface and Requester (DOS only)” on 
page 13-63 


= “Performing Continuous Operations” on page 13-64 


Table 13-6 lists the commands that you can use with the Command- 
line Maintenance Utility. 


Table 13-6 Command-Line Maintenance Utility Commands 























Command Description 

CLONE Creates a new, empty data file using an existing file’s 
specifications. 

CLROWNER Clears the owner name of a data file. 

COPY Copies the contents of one data file to another. 

CREATE Creates a data file. 

DROP Drops an index. 

ENDBU Ends continuous operation on data files defined for 
backup in Win32 and NLM versions only. 
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Table 13-6 Command-Line Maintenance Utility Commands continued 





Command 


Description 





INDEX 


Creates an external index file. 





LOAD 


Loads the contents of an unformatted file into a data file. 





RECOVER 


Reads data sequentially from a data file and writes the 
results to an unformatted file. (The DOS version does not 
support ROLLFWD.) Use this command if you have a 
damaged file. 





ROLLFWD 


Recovers changes made to a data file between the time 
of the last backup and a system failure. 





SAVE 


Reads data along a key path and writes the results to a 
sequential file. 





SETOWNER 


SINDEX 


Assigns an owner name to a data file. 


Creates an index. 





STARTBU 


Starts continuous operation on files defined for backup in 
Win32 and NLM versions only. 





STAT 


Reports statistics about file attributes and current sizes 
of data files. 





(DOS only) 


Unloads the Btrieve Interface and requester. 





VER 











Displays the version of the MicroKernel Database 
Engine and Btrieve Interface Module that is loaded at the 
server. 


Viewing Com- To view a summary of each command usage, enter the following 
mand Usage command at the file server: 


Syntax butil 





~ Note Unless otherwise shown, all command syntax is lowercase on 
UNIX platforms. Windows-based platforms are case insensitive. 
NetWare can be configured to be case sensitive or insensitive, but for 
purposes of discussion, this section assumes case insensitive. 
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The utility displays usage syntax for each command as illustrated in 


Table . 


Table 13-7 Maintenance Utility Command Syntax on NetWare 





bu 


til -clone outputFile sourceFile [/O<owner | *>] [/S] 





bu 


til -clrowner sourceFile /O<owner | *> [/S] 





bu 


til @commandFile [commandOutputFile] 














butil -copy sourceFile outputFile 

[/O< ownerl | *> [/O<owner2 | *>]] [/S] 

butil -create outputFile descriptionFile [< Y | N >] [/S] 
butil -drop sourceFile < keyNumber | SYSKEY > 
[/O<owner | *>] [/S] 





til -endbu < /A | sourceFile | @listFile > [/S] 





til -index sourceFile indexFile descriptionFile 
/O<owner | *>] [/S] 





butil -load unformattedFile outputFile [/O<owner |*>] [/S] 





butil -recover sourceFile unformattedFile [/O<owner |*>] [/ 


Ss] 


butil -rollfwd <sourceFile | volume | drive | @listFile> 





[</L[dumpFile] | /W[dumpFile]> [/T<dataLength>] 
[/E<keyLength>] [/H] [/V] [/O<ownerList | owner> | *]] 
[/A] [/S] 

butil -save sourceFile unformattedFile 

[Y indexFile | N <keyNumber | -1>] [/O<ownerl | *> 
[/O<owner2 | *>]] [/S] 





butil -setowner sourceFile /O<owner | *> level [/S] 





butil -sindex sourceFile <descriptionFile | SYSKEY> 
[keyNumber] [/O<owner | *>] [/S] 





butil -startbu <sourceFile | @listFile> [/S] 





butil -stat <sourceFile> [/O<owner | *>] [/S] 








butil -ver [/S] 
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Note The /S option applies only to the NetWare version of the 
command-line utility. Also, on NetWare you always have to specify the 
full path of the file name such as sys:\pvsw\demodata\tuition.mkd. 





Command For- The format for the Maintenance utility command line is as follows: 


mat 


butil [-command [parameter ...1]1 | @commandFile 


-command A Maintenance utility command, such as COPY. You must 


precede the command with a dash (—), and you must enter a 
space before the dash. Table 13-6 lists the commands. 


parameter Information that the command may require. Discussions of 


the individual commands provide details when applicable. 


@commandFile Fully qualified file name of a command file. 


Command Files You can use a command file to do the following: 


Execute a command that is too long to fit on the command line. 


Execute a command that you use often (by entering the 
command once in the command file and then executing the 
command file as often as you want). 

Execute a command and write the output to a file, using the 
following command format: 


BUTIL @commandFile [commandOutputFile] 


For each command executed, the resulting output file shows the 
command followed by its results. All messages appear on the 
server console screen, as well. 


Execute multiple commands sequentially. 


Command files contain the same information as that required on the 
command line. 


Rules for Command Files 


Observe the following rules when creating a Maintenance utility 
command file: 


You cannot split a single parameter across two lines. 
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Description 
Files 


Extended File 
Support 
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You must end each command with <ends> or [end]. You must also 
end each command with an <end> when trying to execute multiple 
commands. The <end> or [end] must be lowercase. 


Command File Example 


The following is an example command file, COPYCRS.CMD. The 
file calls the BUTIL -CLONE command to create the 
NEWCRS.MKD file by cloning the COURSE.MKD file, and the - 
CREATE command to create the NEWFILE.DTA file by using the 
description provided in the NEWFILES.DES description file. 


-clone newcrs.mkd course.mkd <end> 
-create newfile.dta newfiles.des <end> 


The following command uses the COPYPATS.CMD file and writes 
the output to the COPYPATS.OUT file: 


butil @copypats.cmd copypats.out 


Description files are ASCII text files that contain descriptions of file 
and key specifications that the Maintenance utility can use to create 
data files and indexes. Some users employ description files as a 
vehicle for archiving information about the data files they have 
created. For more information about the description file format, see 
Appendix A“Description Files.” 


The size of the MicroKernel data file can be larger than the operating 
system file size limit. When you export data from an extended 
MicroKernel file to an unformatted file, the size of the unformatted 
file can exceed the MicroKernel file size limit because of the 
differences in the physical format. 


Maintenance detects that the unformatted file has exceeded the file 
size limit (2 GB) and starts creating extension files. This process is 
transparent. Extension files and the original unformatted file must 
reside on the same volume. The extension file uses a naming scheme 
similar to the MicroKernel Database Engine. The first extension file 
is the same base file name with “01” extension. The second 
extension file is “402, and so on. These numbers are printed in hex. 
While the naming convention supports up to 255 extension files, the 
current maximum number of extension files is 32. The maximum 
file size is dependent on the page size. The maximum number of 
pages is 16 million. If your page size is 4096 bytes, then the file can 


Owner Names 


Redirecting Er- 
ror Messages 


ASCII File For- 
mat 
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grow to 64 GB. If your page size is 512 bytes, then the maximum file 
size is 8 GB. 


To SAVE or RECOVER huge files to unformatted files, see the 
respective command. Also, when you import data from an 
unformatted file, the utility detects if the file has extensions and 
loads the data from the extension file. 


The MicroKernel allows you to restrict access to files by specifying an 
owner name. Because owner names are optional, the files you use 
with the utility may or may not require an owner name. If the file 
requires an owner name, you must specify it using the /O option. You 
can specify one of the following: 


= Single owner name. 


= List of up to eight owner names. Separate the owner names with 
commas. 


m Asterisk (*). The utility prompts you for the owner name. With 
the ROLLFWD command, the utility prompts you for a list of 
owner names separated by commas. 


Owner names are case-sensitive. If you enter owner names on the 
command line, the utility discards leading blanks. If you specify an 
asterisk, the utility does not discard leading blanks. 


Be sure that you specify a fully qualified file name (including a drive 
letter or UNC path) when redirecting error messages. 


» To redirect error messages to a file on a Windows NT 
or UNIX server 


= Use the following command format. 


butil -command commandParameters > filePath 
» To redirect error messages to a file on a NetWare 
server 


= Use the following command format. 
load butil -command commandParameters (CLIB OPT) 
/ >filepath 
See “Importing Records From an ASCII File” on page 13-28 in the 


Interactive Maintenance utility section. 
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Rules for Speci- When you run butil on a Windows-based platform or a UNIX- 
fying File based platform, you do not need to specify the name of the path if 
Names on Dif- the data file resides in the same directory as your current directory. 
ferent Plat- 

forms 
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Importing and Exporting Data 


COPY 


This section provides detailed information on importing and 
exporting data using the following BUTIL commands: COPY, 
LOAD, RECOVER, and SAVE. 


Table 13-8 Commands to Import and Export Data 











Command Description 

COPY Copies the contents of one data file to another. 

LOAD Loads the contents of a sequential file into a data file. 
RECOVER Reads data sequentially from a data file and writes the 


results to a sequential file. 





SAVE Reads data along a key path and writes the results to a 
sequential file. 











The COPY command copies the contents of one MicroKernel file to 
another. COPY retrieves each record in the input data file and inserts 
it into the output data file. The record size must be the same in both 
files. After copying the records, COPY displays the total number of 
records inserted into the new data file. 





— Note COPY performs in a single step the same function as a 
RECOVER command followed by a LOAD command. 





Using the COPY command, you can create a data file that contains 
data from an old file, but has new key characteristics. 
» To copy a MicroKernel data file 


1 Use the CREATE command to create an empty data file with the 
desired key characteristics (key position, key length, or duplicate 
key values). 


or 


Use CLONE to create an empty data file using the characteristics 
of an existing file. 


2 Use the COPY command to copy the contents of the existing 


data file into the newly created data file. 
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Format 


BUTIL -COPY sourceFile outputFile [/O< ownerl | *> 
[/O<owner2 | *>]] [/S] 


sourceFile The fully qualified name of the data file from which to 
transfer records. When you run BUTIL for Windows NT/95/ 
98, you do not need to specify the name of the path if the 
data file resides in the same directory as your current 
directory. 


outputFile The fully qualified name of the data file into which to insert 
records. The output data file can contain data or be empty. 
When you run BUTIL for Windows NT/95/98, you do not 
need to specify the name of the path if the data file resides 
in the same directory as your current directory. 


/Oownerl The owner name of the source data file, if required. If only 
the output data file requires an owner name, specify /O 
followed by a blank for owner? (as illustrated in the 
example). 


/Oowner2 The owner name of the output data file, if required. 


/S (NetWare only) By default, the Maintenance utility stops at each full screen 
of output and waits for a keystroke before continuing. With 
the /S option, the utility continuously scrolls output on the 
screen. You cannot use /S on the command line if you 
specify a command file, but you can specify /S with a 
command inside a command file. 


Example 


The following command copies the records in COURSE.MKD to 
NEWCRS.MKD. The COURSE.MKD input file does not require an 
owner name, but the NEWCRS.MKD output file uses the owner 
name Pam. 


butil -copy course.mkd newcrs.mkd /O /OPam 


If you omit the first /O from this example, the utility assumes that the 
owner name Pam belongs to the input data file, not the output data 
file. 


The LOAD command inserts records from an input ASCII file into a 
file. The input ASCII file can be a single file or an extended file (the 
base file plus several extension files). LOAD performs no conversion 
on the data in the input ASCII file. After the utility transfers the 

records to the data file, it displays the total number of records loaded. 


Importing and Exporting Data 





Ài 


~ Note The LOAD command opens the output file in Accelerated mode; 
during a LOAD operation, the MicroKernel does not log the file. If you 
are using archival logging, back up your data files again after using the 
LOAD command. 


Extended files: If the utility finds the next extension file, it continues the 
load process. Do not delete any extension file created earlier by the 
SAVE and RECOVER commands. If the file has three extensions and 
the user deletes the second one, LOAD stops loading records after 
processing the first extension file. 


If SAVE or RECOVER created three extension files and a fourth one 
exists from a previous SAVE or RECOVER, LOAD reads the records 
from the fourth extension and inserts them into the MicroKernel file. 
If a fourth file exists, then you need to delete it before starting the 
LOAD process. 





Before running the LOAD command, you must create the input 
ASCII file and the data file. You can create the input ASCII file using 
a standard text editor or an application; the input ASCII file must 
have the required file format (as explained in “Importing Records 
From an ASCII File” on page 13-28). You can create the data file 
using either the CREATE or the CLONE command. 


Format 


butil -load unformattedFile outputFile [/O<owner |*>] [/S] 


unformattedFile The fully qualified name of the ASCII file containing 
the records to load into a data file. For Windows NT, 
you do not need to specify the name of the path if the 
data file resides in the same directory as your current 
directory. 


outputFile The fully qualified name of the data file into which to 
insert the records. When you run BUTIL for Windows 
NT/95/98, you do not need to specify the name of the 
path if the data file resides in the same directory as 
your current directory. 
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/Oowner The owner name for the data file, if required. 


/S (NetWare only) By default, the Maintenance utility stops at each full 
screen of output and waits for a keystroke before 
continuing. With the /S option, the utility continuously 
scrolls output on the screen. You cannot use /S on the 
command line if you specify a command file, but you 
can specify /S with a command inside a command file. 


Example 


The following example loads sequential records from the 
COURSE.TXT file into the COURSE.MKD file. The owner name of 
the COURSE.MKD file is Sandy. 


butil -load course.txt course.mkd /OSandy 


The RECOVER command extracts data from a MicroKernel file and 
places it in an ASCII file that has the same format as the input ASCII 
file that the LOAD command uses. This is often useful for extracting 
some or all of the data from a damaged MicroKernel file. The 
RECOVER command may be able to retrieve many, if not all, of the 
file’s records. You can then use the LOAD command to insert the 
recovered records into a new, undamaged MicroKernel file. 





Note The Maintenance utility performs no conversion on the data in 
the records. Therefore, if you use a text editor to modify an output file 
containing binary data, be aware that some text editors may change the 
binary data, causing the results to be unpredictable. 





Format 
butil -recover sourceFile unformattedFile [/O<owner |*>] [/S] 
[/Q] [/J] [/T] 
sourceFile The fully qualified name of the data file from which to 
recover data. When you run BUTIL for Windows NT/95/ 
98, you do not need to specify the name of the path if the 
data file resides in the same directory as your current 
directory. 
unformattedFile The fully qualified name of the ASCII file where the utility 
should store the recovered records. 
/Oowner The owner name for the data file, if required. 


Importing and Exporting Data 


/S (NetWare only) By default, the Maintenance utility stops at each full 
screen of output and waits for a keystroke before 
continuing. With the /S option, the utility continuously 
scrolls output on the screen. You cannot use /S on the 
command line if you specify a command file, but you can 
specify /S with a command inside a command file. 


/Q Indicates whether to replace an existing unformatted 
file. By default, the Maintenance utility overwrites the 
existing files. If you specify this option and a file with the 
same name exists, the utility returns an error message. 


The utility also checks whether the MicroKernel file to be 
recovered is extended. If the file is extended, the utility 
checks for files with the same name as the potential 
unformatted extension file. If one of those files exists, 
the utility returns an error message. 


/J Indicates BACKWARD reading of the file. If you specify 
this option, the utility recovers data from the MicroKernel 
file using STEP LAST and PREVIOUS operations. The 
default is forward reading, using STEP FIRST and 
NEXT operations. 


A Indicates FORWARD reading of the file. Although the 
default is forward reading, you can use this option to 
indicate FORWARD and BACKWARD reading. This 
means that if you specify both /I and /J, respectively, the 
utility reads the file forward until it fails. Then it starts at 
the end of the file and reads backwards until it reaches 
the record that failed previously or encounters another 
failure. 


If you specify /J first, the utility reads backwards and 
then reads forward. 


For each record in the source file, if the RECOVER command 
receives a variable page error (Status Code 54), it places all the data 
it can obtain from the current record in the unformatted file and 
continues the recovery process. 


The utility produces the following messages: 


= informs you about the name of the last extension file created 

m checks if the next extension file exists, and if so, tells you to delete 
it 

= if you move the extended unformatted files to a different 


location, you are prompted to move the base file and all of its 
extension files 
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Example 


The following example extracts records from the COURSE.MKD file 
and writes them into the COURSE.TXT file. 


butil -recover course.mkd course.txt 


The SAVE command retrieves records from a MicroKernel file using 
a specified index path and places them in an ASCII file that is 
compatible with the required format for the LOAD command. You 
can then edit the ASCII file and use the LOAD command to store the 
edited data in another data file. (See “Importing Records From an 
ASCII File” on page 13-28 for more information about the ASCII 
file format.) 


SAVE generates a single record in the output ASCII file for each 
record in the input data file. Upon completion, SAVE displays the 
total number of records saved. 





~ Note The Maintenance utility performs no conversion on the data in 
the records. Therefore, if you use a text editor to modify an output file 
containing binary data, be aware that some text editors may change the 
binary data, causing the results to be unpredictable. 





Format 


butil -save sourceFile unformattedFile [Y indexFile | N <keyNumber | 
-1>] [/O<ownerl | *> [/O<owner2 | *>]] [/s1 [/Q] [/d] 


[/T] 

sourceFile The fully qualified name of the data file containing the 
records to save. When you run BUTIL for Windows NT/ 
95/98, you do not need to specify the name of the path 
if the data file resides in the same directory as your 
current directory. 

unformattedFile The fully qualified name of the ASCII file where you want 
the utility to store the records. 

indexFile The fully qualified name of an external index file by 
which to save records if you do not want to save records 
using the default of the lowest key number. 

keyNumber The key number (other than 0) by which to save records 


ifyou do not want to save records using the default of the 
lowest key number. 


/Oowner1 


/Oowner2 


/S (NetWare only) 


/Q 


/J 


Al 
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The specification for saving the records in physical order 
using the Btrieve Step operations. 


The owner name for the source file, if required. If only 
the index file requires an owner name, specify /O 
followed by a blank for owner?. 


The owner name for the index file, if required. 


By default, the Maintenance utility stops at each full 
screen of output and waits for a keystroke before 
continuing. With the /S option, the utility continuously 
scrolls output on the screen. You cannot use /S on the 
command line if you specify a command file, but you can 
specify /S with a command inside a command file. 


Indicates whether to replace an existing unformatted 
file. By default, the Maintenance utility overwrites the 
existing files. If you specify this option and a file with the 
same name exists, the utility returns an error message. 


The utility also checks whether the MicroKernel file to be 
saved is extended. If the file is extended, the utility 
checks for files with the same name as the potential 
unformatted extension files. If one of those files exists, 
the utility returns an error message. 


Indicates BACKWARD reading of the file. If you specify 
this option, the utility recovers data from the MicroKernel 
file using GET LAST and PREVIOUS operations. The 
default is forward reading, using GET FIRST and NEXT 
operations. 


Indicates FORWARD reading of the file. Although the 
default is forward reading, you can use this option to 
indicate FORWARD and BACKWARD reading. This 
means that if you specify both /l and /J, respectively, the 
utility reads the file forward until it fails. Then it starts at 
the end of the file and reads backwards until it reaches 
the record that failed previously or encounters another 
failure. 


If you specify /J first, the utility reads backwards and 
then reads forward. 


The utility produces the following messages: 


= informs you about the name of the last extension file created 


m checks if the next extension file exists, and if so, tells you to delete 


it 
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= if you move the extended unformatted files to a different 
location, you are prompted to move the base file and all of its 
extension files 


Examples 


The following two examples illustrate how to use the SAVE 
command to retrieve records from a data file. 


This example uses a NEWCRS.IDX external index file to retrieve 
records from the COURSE.MKD file and store them in an 
unformatted text file called COURSE.TXT: 


butil save course.mkd course.txt newcrs.idx 


The following example retrieves records from the COURSE.MKD 
file using key number 3 and stores them in an unformatted text file 
called COURSE. TXT: 


butil -save course.mkd course.txt n 3 


Creating and Modifying Data Files 





Creating and Modifying Data Files 


CLONE 


This section includes detailed information on creating and 
modifying data files using the following BUTIL commands: CLONE, 
CLROWNER, CREATE, DROP, INDEX, SETOWNER, and 
SINDEX. This section also includes information about removing 
unused space in a Btrieve data file, which is discussed in 
“Compacting Btrieve Data Files” on page 13-56. 


Table 13-9 Commands to Create and Modify Data Files 

















Command Description 

CLONE Creates a new, empty data file using an existing file’s 
specifications. 

CLROWNER Clears the owner name of a data file. 

CREATE Creates a data file. 

DROP Drops an index. 

INDEX Creates an external index file. 

SETOWNER Assigns an owner name to a data file. 

SINDEX Creates an index. 














The CLONE command creates a new, empty file with the same file 
specifications as an existing file (including any supplemental 
indexes, but excluding the owner name). The new data file includes 
all the defined key characteristics (such as key position, key length, 
or duplicate key values) contained in the existing file. 


The CLONE command ignores all MicroKernel configuration 
options that affect file statistics (such as “System Data” on page 4-11) 
except file version. The CLONE command creates a new file using the 
MicroKernel file version you specify with the Create File Version 
option. 


13-47 


Manipulating Btrieve Data Files with Maintenance 


13-48 


Format 


butil -clone outputFile sourceFile [/O<owner | *>] [/S] 


outputFile The fully qualified file name to use for the new, empty 
data file. When you run BUTIL for Windows NT/95/98, 
you do not need to specify the name of the path if the data 
file resides in the same directory as your current 
directory. 


sourceFile The fully qualified file name of the existing data file to 
replicate.When you run BUTIL for Windows NT/95/98, 
you do not need to specify the name of the path if the data 
file resides in the same directory as your current 
directory. 


/Oowner The owner name, if any, for the source data file. The new 
data file does not have an owner name. See “Owner 
Names” on page 13-37 for more information. 


/S (NetWare only) By default, the Maintenance utility stops at each full 
screen of output and waits for a keystroke before 
continuing. With the /S option, the utility continuously 
scrolls output on the screen. You cannot use /S on the 
command line if you specify a command file, but you can 
specify /S with a command inside a command file. 


Remarks 


Btrieve 6.0 and later allows a maximum of 23 key segments in a data 
file with a page size of 1,024 bytes. Therefore, the CLONE command 
sets the page size in the new data file to 2,048 bytes if the existing data 
file contains 24 key segments and has a page size of 1,024 bytes. This 
occurs if the existing data file has a format earlier than 6.0 and the 
MicroKernel was not loaded with the Create File Version option 
(page 4-10) set to 5.x or 6.x. 


If you are cloning a pre-7.x file, ensure that the MicroKernel is 
configured to create the file format version that you want the new file 
to be. For example, if you want to clone a 6.15 file in 7.x format, 
ensure that the MicroKernel File Format Version option is set to 7.x. 





Note If your source file is in 7.x format and it does not contain system 
data, your output file will not contain system data, regardless of the 
MicroKernel configuration. To add system data to an existing file, refer 
to Getting Started with Pervasive.SQL. 





CLROWNER 


CREATE 


Creating and Modifying Data Files 


If you are trying to recover from receiving Status Code 30 (The file 
specified is not a MicroKernel file) and you suspect that the header 
page of the source file might be damaged, try creating the new 
MicroKernel file using the CREATE command with a description 
file. 


Example 


The following command creates the NEWCRS.MKD file by cloning 
the COURSE.MKD file. 


butil -clone newcrs.mkd course.mkd 


The CLROWNER command clears the owner name of a 
MicroKernel file. 


Format 


butil -clrowner sourceFile </O<owner | *> [/S] 


sourceFile The fully qualified file name of the data file. When you run 
BUTIL for Windows NT/95/98, you do not need to specify 
the name of the path if the data file resides in the same 
directory as your current directory. 


/Oowner The owner name to clear. See “Owner Names” on page 13- 
37 for more information. 


/S (NetWare only) By default, the Maintenance utility stops at each full screen 
of output and waits for a keystroke before continuing. With 
the /S option, the utility continuously scrolls output on the 
screen. You cannot use /S on the command line if you 
specify a command file, but you can specify /S with a 
command inside a command file. 


Example 


The following command clears the owner name for the 
TUITION.MKD file. The owner name for the file is Sandy. 


butil -clrowner tuition.mkd /OSandy 


The CREATE command generates an empty MicroKernel file using 
the characteristics you specify in a description file. Before you can 
use the CREATE command, you must create a description file to 
specify the new key characteristics. For more information, see 
Appendix A “Description Files.” 
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Format 


butil -create outputFile descriptionFile [< Y | N >] [/S] 


outputFile The fully qualified file name of the MicroKernel file to 
create. If the file name is the name of an existing 
MicroKernel file, this command creates a new, empty 
file in place of the existing file. Any data that was stored 
in the existing file is lost and cannot be recovered. 
When you run BUTIL for Windows NT/95/98, you do 
not need to specify the name of the path if the data file 
resides in the same directory as your current directory. 


descriptionFile The fully qualified name of the description file 
containing the specifications for the new MicroKernel 
file. 

YIN Indicates whether to replace an existing file. If you 


specify N but a MicroKernel file with the same name 
exists, the utility returns an error message. The default 
is Y. 


/S (NetWare only) By default, the Maintenance utility stops at each full 
screen of output and waits for a keystroke before 
continuing. With the /S option, the utility continuously 
scrolls output on the screen. You cannot use /S on the 
command line if you specify a command file, but you 
can specify /S with a command inside a command file. 


Example 


The following command creates a file named COURSE.MKD using 
the description provided in the CREATE.DES description file. 


butil -create course.mkd create.des 


Sample Description File for the CREATE Command 


The sample description file shown in Figure 13-16 creates a 
MicroKernel formatted file. The file is specified to have a page size of 
512 bytes and 2 keys. The fixed-length portion of each record in the 
file is set to 98 bytes. The file specifies variable-length records with 
no blank truncation, data compression, and variable-tail allocation 
tables (VATs). The free space threshold is set to 20 percent. Allocation 
is set to 100 pages. The MicroKernel preallocates 100 pages, or 51,200 
bytes, when it creates the file. 


DROP 


Creating and Modifying Data Files 


Figure 13-16 Sample Description File for the CREATE Command 





record=98 variable=y truncation compress=y 
key=2 pate=512 allocation=100 replace=n File Specifications 
fthreashold=20 vats=y 


position=1 length=5 duplicates=y 


modifiable=n type=string alternate=y dd t1 
mullkey=allsegs value=20 segment=y tl egmen 
position=6 length=10 duplicates=y Key 0 
modifiable=n type=string alternate=y ae t2 
egmen 


nullkey=allsegs value=20 segment=n 


position=16 length=2 duplicates=n 
modifiable=y type=numeric descending=y Key 1 
alternate=y nullkey=n segment=n 





name=sys: \pvsw\demodata\upper.alt 











Key 0 is a segmented key with two duplicatable, nonmodifiable 
string segments and a null value of 20 hexadecimal (space) specified 
for both segments. Key 0 uses the collating sequence UPPER.ALT. 


Key 1 isa numeric, nonsegmented key that does not allow duplicates 
but permits modification. It is sorted in descending order. 


The DROP command removes an index from a file and adjusts the 
key numbers of any remaining indexes, subtracting 1 from each 
subsequent key number. If you do not want to renumber the keys, 
you can add 128 to the key number you specify to be dropped. This 
renumbering feature is available only for 6.0 and later files. 


Format 


butil -drop sourceFile < keyNumber | SYSKEY > 
[/O<owner | *>] [/S] 


sourceFile The fully qualified name of the file from which you are 
dropping the index. When you run BUTIL for Windows 
NT/95/98, you do not need to specify the name of the 
path if the data file resides in the same directory as 
your current directory. 


keyNumber The number of the key to remove. To preserve the 


original key numbers, add a 128 bias to the key number 
you specify. 
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SYSKEY Instructs the utility to drop the system-defined log key 
(also called system data). Dropping the system- 
defined log key does not delete values from the 
records; the MicroKernel still assigns unique system- 
defined log key values to newly inserted records. 


However, the MicroKernel cannot perform logging for a 
file from which the system-defined log key is dropped, 
if no user-defined unique keys exist. For this reason, 
you should use this option only if you suspect that the 
system-defined log key is corrupt and you intend to re- 
add it. 


The SINDEX command allows you to re-use the 
system-defined log key once you have dropped it. 


/Oowner The owner name for the file, if required. 


/S (NetWare only) By default, the Maintenance utility stops at each full 
screen of output and waits for a keystroke before 
continuing. With the /S option, the utility continuously 
scrolls output on the screen. You cannot use /S on the 
command line if you specify a command file, but you 
can specify 
/S with a command inside a command file. 


Examples 


In both of the following examples, COURSE.MKD has three keys. 
The original keys in the file are numbered 0, 1, and 2. 


In the first example, the BUTIL-DROP command drops key number 
1 from the COURSE.MKD file and renumbers the remaining key 


numbers as 0 and 1. 
butil -drop course.mkd 1 


In the following example, the BUTIL -DROP command drops key 
number 1, but does not renumber the keys. The key numbers remain 
0 and 2. 


butil -drop course.mkd 129 


The INDEX command builds an external index file for an existing 
MicroKernel file, based on a field not previously specified as a key in 
the existing file. Before you can use the INDEX command, you must 
create a description file to specify the new key characteristics. For 
more information about description files, see Appendix A 
“Description Files.” 


Creating and Modifying Data Files 


The records in the new file consist of the following: 


m The 4-byte address of each record in the existing data file. 


m The new key value on which to sort. 





Note If the key length you specify in the description file is 10 bytes, the 
record length of the external index file is 14 bytes (10 plus the 4-byte 
address). 





Format 
butil -index sourceFile indexFile descriptionFile [ /O<owner | *>] 
[/S] 

sourceFile The fully qualified name of the existing file for which to 
build an external index. When you run BUTIL for 
Windows NT/95/98, you do not need to specify the 
name of the path if the data file resides in the same 
directory as your current directory. 

indexFile The fully qualified name of the index file in which the 
MicroKernel should store the external index. 

descriptionFile The fully qualified name of the description file you have 
created containing the new key definition. The 
description file should contain a definition for each 
segment of the new key. 

/Oowner The owner name for the data file, if required. 

/S (NetWare only) By default, the Maintenance utility stops at each full 
screen of output and waits for a keystroke before 
continuing. With the /S option, the utility continuously 
scrolls output on the screen. You cannot use /S on the 
command line if you specify a command file, but you 
can specify /S with a command inside a command file. 

Remarks 


The INDEX command creates the external index file and then 
displays the number of records that were indexed. To retrieve the 
data file’s records using the external index file, use the SAVE 
command. 
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Sample Description File for the INDEX Command 


The description file shown in the following illustration defines a new 
key with one segment. The key begins at byte 30 of the record and is 
10 bytes long. It enables duplicates, is modifiable, is a STRING type, 
and uses no alternate collating sequence. 


Figure 13-17 Sample Description File for INDEX Command 





position=30 length=10 duplicates=y modifiable=y 
type=string alternate=n segment=n 





Example 


The following command creates an external index file called 
NEWCRS.IDX using a data file called COURSE.MKD. The 
COURSE.MKOD file does not require an owner name. The 
description file containing the definition for the new key is called 
NEWCRS.DES. 


butil -index course.mkd newcrs.idx newcrs.des 


The SETOWNER command sets an owner name for a MicroKernel 
file. 


Format 


butil -setowner sourceFile /O<owner | *> level [/S] 


sourceFile The fully qualified name of the data file. When you run 
BUTIL for Windows NT/95/98, you do not need to 
specify the name of the path if the data file resides in 
the same directory as your current directory. 


/Oowner The owner name to be set 


level The type of access restriction for the data 
file. The possible values for this parameter 
are as follows 


0: Requires an owner name for any access mode (no 
data encryption) 


SINDEX 


Creating and Modifying Data Files 


1: Permits read access without an owner name (no 
data encryption) 


2: Requires an owner name for any access mode (with 
data encryption) 


3: Permits read access without an owner name (with 
data encryption) 


/S (NetWare only) By default, the Maintenance utility stops at each full 
screen of output and waits for a keystroke before 
continuing. With the /S option, the utility continuously 
scrolls output on the screen. You cannot use /S on the 
command line if you specify a command file, but you 
can specify /S with a command inside a command file. 


Example 


The following example creates an owner for the COURSE.MKD file. 
The owner name is Sandy, and the restriction level is 1. 


butil -setowner course.mkd /OSandy 1 


The SINDEX command creates an additional index for an existing 
MicroKernel file. By default, the key number of the new index is one 
higher than the previous highest key number for the data file, or you 
can instruct the MicroKernel to use a specific key number. An 
exception is if a DROP command previously removed an index 
without renumbering the remaining keys, thus producing an unused 
key number; in this case, the new index receives the first unused 
number. 


You can instruct the MicroKernel to use a specific key number for the 
new index with the key number option. The key number you specify 
must be a valid key number that is not yet used in the file. If you 
specify an invalid key number, you receive Status Code 6. 


If you do not use the SYSKEY option with this command, you must 
create a description file that defines key specifications for the index 
before you can use the SINDEX command. For more information 
about description files, see Appendix A “Description Files.” 
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Format 


butil -sindex sourceFile <descriptionFile | SYSKEY> [keyNumber] 


[/O<owner | *>] 


sourceFile 


descriptionFile 


SYSKEY 


/Oowner 


/S (NetWare only) 


Examples 


[/S] 


The fully qualified name of the existing file for which to 
build an external index. When you run BUTIL for 
Windows NT/95/98, you do not need to specify the 
name of the path if the data file resides in the same 
directory as your current directory. 


The fully qualified name of the description file you have 
created containing the new key definition. The 
description file should contain a definition for each 
segment of the new key. 


Instructs the utility to re-add the system key on a file in 
which the system key was dropped. 


The owner name for the data file, if required. 


By default, the Maintenance utility stops at each full 
screen of output and waits for a keystroke before 
continuing. With the /S option, the utility continuously 
scrolls output on the screen. You cannot use /S on the 
command line if you specify a command file, but you 
can specify /S with a command inside a command file. 


The following example adds an index to the COURSE.MKD file. The 
name of the description file is NEWIDX.DES. 


butil -sindex course.mkd newidx.des 


The following example adds the system-defined key to the 
COURSE.MKD file. The system-defined key was dropped. 


butil -sindex course.mkd syskey 


You can use several commands in the BUTIL (CLONE, RECOVER, 
and LOAD, respectively) to remove unused space in a data file to 


decrease its size. 


»> To compact a Btrieve data file 


1 Rename your data file and then use the CLONE option to create 
a blank data file using the original file name. 


2 Use RECOVER to save the data from the clone file to an 
unformatted text file in sequential order. 


Creating and Modifying Data Files 


Use LOAD to load the recovered data into the clone. 


Every record containing data will load into the newly created 
data file without blank records. 





Note You can also perform this operation in the Btrieve Interactive 
Maintenance utility. 
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This section includes information about generating a report that 
contains a data file’s characteristics and statistics using STAT. 


The STAT command generates a report that contains defined 
characteristics of a data file and statistics about the file’s contents. 
Using the STAT command is a good way to determine if a file can be 
logged by the MicroKernel’s transaction durability feature. The 
STAT command reports indexes the same whether they were created 
by the Create Supplemental Index operation (in Btrieve 6.0 and 
later) or the Create operation. 


Format 


butil -stat <sourceFile> [/O<owner | *>] [/S] 


sourceFile 


/Oowner 


/S (NetWare only) 


Example 


The fully qualified name of the data file for which to report 
statistics. For Windows NT, you do not need to specify the 
name of the path if the data file resides in the same directory 
as your current directory. 


The owner name for the data file, if required. 


By default, the Maintenance utility stops at each full screen 
of output and waits for a keystroke before continuing. With 
the/S option, the utility continuously scrolls output on the 
screen. You cannot use /S on the command line if you 
specify a command file, but you can specify /S with a 
command inside a command file. 


The following example reports file statistics for the PATIENTS.DTA 
file. The data file does not have an owner name. 


butil -stat patients.dta 


However for NetWare, you must specify the full path such as: 


butil -stat sys:\pvsw\demodata\patients.dta. 


The following example shows the resulting report: 


kkkkkxkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkxk 


File Statistics for PATIENTS .DTA 


File Version 


= 7.00 


Viewing Data File Statistics 


Page Size = 2048 

Page Preallocation = No 
Key Only = No 

Extended = No 


Total Number of Records = 16 
Record Length = 104 

Data Compression = No 
Variable Records = No 


Available Linked Duplicate Keys = 0 
Balanced Key = No 
Log Key = 1 
System Data = No 
Total Number of Keys = 3 
Total Number of Segments = 4 


Key Segment Position Length Type Flags 
Null Values* Unique ACS Values 


0 1 20 20 String MD 
5s 16 0 
0 2 7 12 String MD 
ae 16 0 
T 1 1 6 String M 
zis 16 0 
2 1 83 10 String MD 
== y 0 


Alternate Collating Sequence (ACS) List: 
O UPPER 


Legend: 

< = Descending Order 
= Duplicates Allowed 
= Case Insensitive 
= Modifiable 
Repeat Duplicate 
= Any Segment (Manual) 
= All Segments (Null) 
= The values in this column are hexadecimal. 
= Unknown 
-- = Not Specified 


vt pa eHvU 
Il 


“Y 


This example shows that the file called PATIENTS.DTA is a 7.0 file. 
(The version number indicates the earliest Btrieve version that can 
read the file format.) The file has a page size of 2,048 bytes and has 
no preallocated pages. This is not a key-only file, nor is it an extended 
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Sixteen records have been inserted into the file. The file was defined 
with a record length of 104 bytes, does not use data compression, and 
does not allow variable-length records. 


There are no linked duplicate keys available in the file. The file does 
not use balanced indexing. The MicroKernel performs logging using 
Key 1, and the file contains no system-defined data. The file has three 
keys comprised of four key segments. 





— Note Indexes created with SINDEX are designated with the letter R by 
default unless you specified the Reserved Duplicate Pointer element. 





The STAT report also provides information about specific keys. For 
example, the report shows that Key 0 allows duplicates, is modifiable, 
and consists of two segments: 


= The first segment starts in position 21, is 20 characters long, 
allows duplicates, is modifiable, and will be sorted as a STRING 
type. The dashes indicate that a null value was not defined. The 
Unique Values column indicates that 16 unique values were 
inserted for this segment. This segment uses the UPPER.ALT 
alternate collating sequence file. 


m The second segment starts in position 7, is 12 characters long, 
allows duplicates, is modifiable, and will be sorted as a STRING 
type. Sixteen unique values were inserted for this segment. This 
segment uses the UPPER.AIT alternate collating sequence file. 


Key 1 is the key the MicroKernel uses in logging this file. Key 1 
consists of one segment. It starts in position 1, is six characters long, 
does not allow duplicates, is modifiable, and will be sorted as a 
STRING type. Sixteen unique values were inserted for this key. This 
key uses the UPPER.AIT alternate collating sequence file. 


Key 2 consists of one segment. It starts in position 83, is 10 characters 
long, allows duplicates, is modifiable, and will be sorted as a STRING 
type. Seven unique key values were inserted for this key. This key uses 
the UPPER.ALT alternate collating sequence file. 


File Version Notes 


When reporting the file format version for a file, the MicroKernel 
reports the earliest engine version that can read the specified file. For 
example, you may have a file that was created in Btrieve 5.x format, 


Viewing Data File Statistics 


but it may be reported as a version 3.x file because it does not use any 
4.x or 5.x features. Starting with the 6.x format, the file itself contains 
a version stamp. Prior to 6.x, the only way to determine the file 
format version of a file is by inspecting the features that it uses. For 
version 5.x or earlier files, the table below shows the features which, 
if used, determine the version that is reported for the file: 


Table 13-10Version 5.x and Earlier File Format Features 











This file format version is | ... if one or more of these features are in use: 
reported ... 
5.x Compressed records 
Key only file 
4.x Extended key types 


Variable length records 
Index added with Createlndex operation 


3.x None of the above 
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This section includes detailed information about displaying the 
version of the Btrieve Interface module using the VER command. 


The VER command returns the version number of both the 
MicroKernel and the Btrieve Access Module. 


Format 


butil -ver [/S] 


/S (NetWare only) By default, the Maintenance utility stops at each full screen 
of output and waits for a keystroke before continuing. With 
the /S option, the utility continuously scrolls output on the 
screen. You cannot use /S on the command line if you 
specify a command file, but you can specify /S with a 
command inside a command file. 


Remarks 


When you run the VER command, the utility displays messages 
similar to the following; 


The Btrieve Requester version is 7.50. 
The Btrieve Version is 7.50. 


Unloading the Btrieve Interface and Requester (DOS only) 





Unloading the Btrieve Interface and Requester (DOS only) 


STOP 


Use the STOP command to unload the Btrieve Interface and, if 
applicable, the requester. 


Format 


butil -stop 
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Performing Continuous Operations 


The commands pertaining to continuous operations, startbu and 
endbu, are discussed in the chapter “Backup and Restore” on page 8- 
1. 
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Maintaining Pervasive.SQL File Compatibility 


Pervasive.SQL 2000i includes several tools that convert old Btrieve 
and Pervasive.SQL files to be compatible with the latest versions of 
the Pervasive.SQL engines. This chapter describes those tools, why 
you might need to use them and how to do so. This chapter includes 
the following sections: 


=» “Null Conversion” on page 14-2 


m “Converting MicroKernel Data Files” on page 14-5 
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The Null Conversion Utility adds or removes support for nullable 
columns in Pervasive.SQL tables. The utility allows users to: 

= Convert legacy tables into Pervasive.SQL 20001 format 

= Change not-nullable columns to nullable 

= Change nullable columns to not-nullable 

In Pervasive.SQL 2000i, null values are added as an extra byte to the 
default record. If you set this extra byte as any value other than zero, 


it is designated as null. This extra byte can be used to define the 
index. If a field is not defined as nullable, no extra bytes are added. 





~~ Note There are a maximum number of segments allowed per file. In 
Pervasive.SQL 2000i, true null columns contain two segments per 
index. Therefore, it is important to keep in mind that defining null 
values doubles the number of segments used. See the Pervasive.SQL 
Programmer's Guide for more information about maximum Btrieve 
segment sizes. 





~ Note In a case where a user converts an existing table with legacy nulls 
and the null values differ from the defaults, the Null Conversion utility 
will allow the user to specify which value(s) should be considered null 
for each column. 


The Null Conversion utility is implemented as a wizard with the 
Pervasive.SQL Control Center framework. 
» To convert a table's nullable fields: 


1 Open on the Databases namespace node under a machine in the 
Control Center namespace tree. 


2 Right-click on the desired database in the namespace. 
3 Select Tasks, then Null Conversion in the shortcut menu. 


4 The wizard presents a dialog box in which the user can specify 
which tables in the database are to undergo null conversion. 


Null Conversion 


Figure 14-1 Null Conversion Wizard Dialog Box 


| Nui Conversion Wizard for Pervasive SQL 2000 


Specify tables for conversion 
Select tables for conversion and type of conversion. 





PSQL.2000 
PSQL.2000 
PSQL.2000 
PSOL.2000 











00 
PSQL.2000 
PSQL.2000 
PSQL.2000 
PSQL.2000 
PSQL.2000 



































Click the check box under the Convert column for those tables 
that are to be converted. Click Next when done. 


5 Next, the wizard presents a dialog box allowing the indication of 
which fields are currently nullable. These values may be changed 
at this time. 


Figure 14-2 Null Conversion Wizard - Specify Columns for Conversion Dialog 
Box 


Null Conversion Wizard for Pervasive SQL 2000 


Specify columns for conversion 
Select result columns’ properties and type of conversion. 
Please note: null values are hexadecimal numbers. 





ID IDENTITY 
Name CHAR 
Section CHAR 
Max_Size USMALLINT 
Start_Date DATE 
Start_Time TIME 
Finish_Time TIME 
Building Name | CHAR 
Room Number | UINTEGER 


= 
= 





























Faculty_ID UBIGINT 
Name CHAR 
Phone_Number_| DECIMAL 
Department Building Name | CHAR 























BEER ooo 00 





JORKDOODoOonooxnooa 
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Note Some data types are not nullable, such as BIT and AUTOINC. 





6 Before changes are committed to the database the following 
dialog box displays the actions that are to be taken. 


Figure 14-3 Null Conversion Wizard - Completing Dialog Box 





Null Conversion Wizard for Pervasive SQL 2000 


Completing the Null Conversion Wizard 


You have successfully specified information necessary to 


start conversion process. Review the selections below and 
click on CONVERT to execute. 


Summary: 


Tables for conversion: 
Class - convert to True NULL 
Department - convert to True NULL 
Faculty - convert to True NULL 














To stop the operation, click Cancel. To continue, click Convert. 


7 Finally, the Null Conversion Wizard indicates that the selected 
tables were converted successfully (not shown). 
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Converting MicroKernel Data Files 


The Rebuild utility is a tool that can convert older Btrieve data files 
to the current Pervasive.SQL format. While the current engines 
remain compatible with the older files, there are several reasons for 
converting the files including support for nullable columns and 
performance improvements. 


Table 14-1 Rebuild Utility Conversions 





Original File Converted File Reason for Conversion 
Format Format 
Pre-7.x 7.X Take advantage of 7.x features and 


improve general performance. 





7.X 7.X Original file does not have a system key. 





Pre-6.0 6.x Take advantage of 6.x features and 
improve general performance. Use this 
option only if you are still running the 7.x 
engine with other 6.x engines. 














The Rebuild utility comes in three forms with Pervasive.SQL 2000i: 
a 32-bit GUI version for Windows 95/98/NT, a 16-bit GUI version 
for Windows 3.x and a command-line version that runs as an NLM 
on NetWare. 


The file format that results from the conversion depends on the value 
set for the MicroKernel's Create File Version configuration option. 
For example, if the Create File Version value is 7.x then running the 
Rebuild utility on version 6.x files will result in the rebuilt files being 
converted to version 7.x format. 





Note If your files are already in 7.x format, you do not need to rebuild. 
Pervasive.SQL 2000i has the same file format as Pervasive.SQL 7. 





Before running the Rebuild utility, back up all the data files you plan 
to convert. Having backup copies ensures against data loss if a power 
interruption occurs while the utility is running. To ensure that the 
backup is successful, perform one or more of the following 
operations: 


= Close all data files before running the backup utility. 
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Use continuous operations. 

Use a backup utility that opens the files in exclusive write mode 
so that other processes cannot write to the files. Ensure that the 
backup utility has exclusive rights to the files. 





Note You cannot run the Rebuild utility on a file that is in continuous 
operation mode. 





There are three ways to start the GUI Rebuild utility: 


On a 32-bit Windows machine, select Tools, then Rebuild from 
the Pervasive Control Center menu. 

On a 32-bit Windows machine, from the Windows Start menu, 
select Programs, then Pervasive, then Pervasive.SQL 2000i, then 
Utilities, then Rebuild. 

On a 16-bit Windows machine, in the Pervasive.SOL 20001 
program group, double-click the Rebuild utility icon. 


The main window displays as illustrated in Figure 14-4. 


Figure 14-4 Rebuild Utility Main Window 








Rebuild Utility 





You can access a Help file from either the Help menu or by clicking 
Help in any dialog box. 


Converting a 
Data File 


Converting MicroKernel Data Files 


»> To convert a data file: 


1 


Choose Select Files from the Options menu. The Select Files 
dialog box appears (Figure 14-5.) 


Figure 14-5 Select Files Dialog Box 


E Select Files Lx] 


Selected Files: 








Click Add and select the file you want to rebuild. You can select 
more than one file to rebuild at a time. Click OK when you have 
finished adding files to rebuild. 


The Rebuild utility deletes the original file after rebuilding it if 
the file is being rebuilt in the same directory. If the new file is in 
a different directory, the original file is not deleted. 


Before you rebuild the file(s), you may want to specify settings. 
Choose Settings from the Options menu. The Settings dialog 
box displays as illustrated in Figure 14-6. 
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Figure 14-6 Settings Dialog Box 











ml Settings 
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You can change the configuration options for the Rebuild utility 
before you rebuild your selected file or files. These options are 
defined in Table 14-2. 


Table 14-2 Controls in the Settings Dialog Box 








Control Description 
Output Specifies an alternate location for the rebuilt files. (The default 
Directory location is the current directory.) You must specify a directory 


that already exists. 


This option lets you rebuild large files on a different server. The 
MicroKernel and its communications components must be 
loaded on the server that contains the rebuilt files. Do not use 
wildcard characters in the path. 


If the Output Directory location is different than the original file's 
location, the original file is not deleted during the rebuild. If the 
output directory is the same as the original file, the original file 
is deleted upon completion of the rebuild. 





Key Number Specifies the key by which the utility reads when rebuilding a 
file. If you specify NONE for this option, the utility clones the 
files, drops the indexes, copies the records into the new files, 
and rebuilds the indexes. Because this method is faster and 
creates smaller files than specifying a key number, use it 
whenever possible. 


This method may create a new file in which the records are ina 
different physical order than in the original file. 


If you specify a key number, the utility clones and copies the files 
without dropping and replacing indexes. While this method is 
slower than specifying NONE, it is available in case you do not 
want to rebuild your indexes. 





Status File Path | Specifies a location for the rebuild log file. (The default location 
is the current working directory.) Do not use wildcard characters 
in the path. 





Page Size Specifies the page size (in bytes) of the new files. Choose either 
EXISTING, 512, 1024, 2048, 3072, or 4096. If you select 
EXISTING, the utility uses the existing page size. The utility 
changes the page size if the original size does not work. 


For example, assume you have a v5.x file with a page size of 
1,024 and 24 keys. Because Btrieve 6.0 and later supports only 
23 keys for a page size of 1,024, the utility automatically selects 
a new page size for the file and writes an informative message 
to the status file. 
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Table 14-2 Controls in the Settings Dialog Box continued 








Control Description 
Continue on Determines whether the Rebuild utility continues if it encounters 
Error an error during the rebuild process. If you select Yes, the utility 


continues with the next file even if an error occurs. The utility 
notifies you of non-MicroKernel data files or other errors but 
continues rebuilding data files. If you select No, the utility halts 
the rebuild if it encounters an error. 


This option is useful if you have specified wildcard characters for 
the rebuilt files. 





Save Settings 
Upon Exit 


Saves the current values in this dialog box for use in subsequent 
Rebuild sessions. 





Choose System 
Data and Key 











Specifies whether the file is rebuilt with System Data or System 
and Key Data. The MicroKernel cannot perform logging for a file 
without system data when no user-defined unique key exists. 


4 After you specify the settings, you need to start the file 
conversion process. Select Start Rebuild from the Run menu. 
The Start Rebuild dialog box displays as indicated in Figure 14-7. 


Figure 14-7 Start Rebuild Dialog Box 


imi Start Rebuild El 


Files to Rebuild: 


CAPVSWAdemodatatclass.mkd 
C:\P¥SW\demodata\dept.mkd 
C:\P¥SW\demodata\faculty.mkd 





5 Click Start to begin the rebuild process, which converts all of the 


listed files. 


When the process completes, a message dialog box informs of 
the success or failure of the conversion and prompts you to view 


the results. 


6 Click Close when you have finished converting files. 
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7 To display the results, select View Status File from the Run 
menu. The REBUILD.LOG file is displayed as illustrated in 
Figure 14-8. 


Figure 14-8 Rebuild Log Display 


E View File: CAPYSWABINtrebuild.log 


The rebuild start time is Fri Dec 15 17:03:19 2000. 
Pervasive Software Rebuild Utility 
Rebuild Options: 

Continue on Error: No 

System Data: No 

Page Size: EXISTING 

Key Number: NONE 

Output Directory: c:\program files\common files\system\mapi\1 033\nt 
Rebuild is processing CAPYSWAdemodatalperson.mkd. 
Rebuild copied a total of 1500 records. 
The file was rebuilt successfully. 


The rebuild ending time is Fri Dec 15 17:03:23 2000. 


The rebuild start time is Fri Dec 15 17:03:23 2000. 
Pervasive Software Rebuild Utility 
Rebuild Options: 





The Rebuild utility writes to the status file for every file it 
attempts to convert. The log file (REBUILD.LOG by default) is 
an ASCII text file that is placed by default in the directory in 
which you run the Rebuild utility from. 


You can examine the log file by selecting the View Status File 
command from the Run menu. The rebuild settings are listed for 
every file. If you disabled the Continue on Error setting, the 
status file contains the information up to the point of the error. 
If the rebuild was not successful, the status file contains error 
messages explaining why the rebuild failed. 
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Command-Line Rebuild Utility 


This section provides detailed instructions for using the command- 
line Rebuild utility which runs only as an NLM on NetWare. 





— Note When rebuilding a data file larger than 10MB, BREBUILD.NLM 
can hog CPU on the NetWare platform. Pervasive recommends that 
you perform such tasks directly at the file server console when server 
usage is low. 





Running the > To run the Rebuild utility for NetWare: 
Rebuild Utility, 


Run RCONSOLE from a workstation, or go to the server’s 
on NetWare 


console. 
2 Enter one of the following commands at the prompt: 


LOAD BREBUILD [-option ...] file 


or 








LOAD BREBUILD @command_file 
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Changing Con- > To change the configuration options for the Rebuild 
figuration Op- utility for NetWare: 


tions 


The Option command specifies the configuration options for the 


utility. Precede each option letter with a dash (—). Do not place a 
space between the dash and the option letter or between the 
option letter and its value. You can enter the option letter in 
either uppercase or lowercase. 


—B[path] 
-C 

-D 

—M0 | -M2 


Specifies an alternate location for the rebuilt files. (The 
default location is the current directory.) You can also 
specify a different server with this option. On your local 
server, you must have the MicroKernel Database Engine 
and the Message Router loaded. On a remote server, 
you need the MicroKernel Database Engine and 
communications components loaded. Do not use 
wildcard characters in the path you specify. 


Instructs the utility to continue with the next file even if an 
error occurs. The utility notifies you of non-MicroKernel 
data files or other errors but continues rebuilding data 
files. 


This option is useful if you have specified wildcard 
characters for the rebuilt files. 


Converts pre-6.0 supplemental indexes (which allow 
duplicates) to 6.x or 7.x indexes with linked-duplicatable 
keys. (By default, the utility preserves the indexes as 
repeating-duplicatable keys.) If you access your data 
files only through Btrieve and your files have a relatively 
large number of duplicate keys, you can use this option 
to enhance the performance of the Get Next and Get 
Previous operations. 


If you are using Scalable SQL to access your data files, 
do not use the —D option. 


Specifies the conversion method, as follows: 
Clones and copies the files without dropping and 
replacing indexes. While this method is slower than M2, 


it is available in case you do not want to rebuild your 
indexes. 
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-M2 (Default) Clones the files, drops the indexes, copies the 
records into the new files, and rebuilds the indexes. 
Since this method is faster and creates smaller files than 
the MO method, use it whenever possible. 


The M2 method may create a new file in which the 
records are in a different physical order than in the 
original file. 


—P[nnn] Specifies the page size (in bytes) of the new files. If you 
specify —P with no page size, the utility chooses the 
optimum page size for your file. 


If you do not specify the —P parameter, the utility 
changes the page size if the original size does not work. 


For example, assume you have a v5.x file with a page 
size of 1024 and 24 keys. Since Btrieve 6.0 and later 
supports only 23 keys for a page size of 1024, the utility 
automatically selects a new page size for the file and 
displays an informative message on the screen. 


—K[nn] Specifies the key by which the utility reads when 
rebuilding a file. If you do not specify this option, the 
utility reads the file in physical order. 


-T Does not preserve the Transaction Tracking System 
(TTS) bit during conversion. If you specify this option, 
the utility clears the TTS bit if it was set. If you do not 
specify this option, the utility sets the TTS bit when 
creating the new file if the original file had the TTS bit 
set. 
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File and @command_file are defined as follows: 


file Specifies the set of files to convert. Use full directory 
names, including the volume name. You may use wildcard 
characters (* and ?) in these file names. The Rebuild utility 
applies the original file's owner name and level to the new 
file. 


@ command. file Specifies a command file for the utility to execute. You can 
include multiple entries in one command file. Each entry in 
the command file contains the utility options (if any) and 
the set of files to convert, followed by <end> or [end]. 
When specifying the files to convert, be sure to use full 
directory names, including the volume name. You can use 
wildcard characters (* and ?) in these file names. 


The following is an example of a Rebuild utility command 
file: 


-C sys:\mydir\*.* <end> 
-C -P1024 dta:\dir\*.* <end> 
-MO -KO sys:\ssql\*.* <end> 


The following example places the rebuilt files in a different 
directory on the server: 


LOAD BREBUILD -Bsys:\newfiles -C -P4096 
sys:\oldfiles\*.mkd 


Viewing the After rebuilding your files, check the utility’s log file to see if any 
BRE- errors occurred during the conversion. The BREBUILD.LOG is an 
BUILD.LOG File ASCII text file, which is placed in the SYSASYSTEM directory. You 


can examine the log file using a text editor. 
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Deleting Temporary Files 
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By default, the Rebuild utility creates temporary files in the same 
directory in which the conversion takes place. Therefore, you need 
enough disk space in that directory (while the Rebuild utility is 
running) to accommodate both the original file and the new file. You 
can specify a different directory for storing these files using the 
Output Directory option in the interactive version of the utility or 
using /B option in the NetWare version. 


Normally, the Rebuild utility deletes temporary files when the 
conversion is complete. However, if a power failure or other serious 
interruption occurs, the Rebuild utility may not delete the 
temporary files. If this occurs, look for file names such as _T- 
xxxxx.TMP and delete them. 
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Using Description Files to Store Btrieve File Information 


A description file is an ASCII text file that contains descriptions of file 
and key specifications that the Maintenance utility can use to create 
data files and indexes. Some users employ description files as a 
vehicle for archiving information about the data files they have 
created. Description files are not the same as DDFs, or Data 
Dictionary Files, which are used with the SQL Interface and the 
ODBC Interface. 


Description files contain one or more elements. An element consists 
of a keyword, followed by an equal sign (=), followed by a value (with 
no space). Each element in a description file corresponds to a 
particular characteristic of a data file or key specification. 





~ Note Before using description files, you should be familiar with 
Btrieve fundamentals, such as data compression and index balancing. 
For information about these topics, refer to the Pervasive.SQL 
Programmer’s Guide. 





This appendix discusses the following topics: 
m “Rules for Description Files” on page A-2 
= “Description File Examples” on page A-4 


= “Description File Elements” on page A-7 
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Use the following rules when creating a description file. 


Enter elements in either uppercase or lowercase. 


Separate elements from each other with a separator (blank space, 
tab, or carriage return/line feed), as in the following example: 


record=4000 

key=24 

Specify the description file elements in the proper order. Table 
A-1 on page A-7 presents the elements in the appropriate order. 
Address all element dependencies. For example, if you specify 
nullkey=allsegs in your description file, you must also specify 
a value for the value= element. 

Define as many keys as you specify with the Key Count element. 
For example, if you specify key=12, you must define 12 keys in 
the description file. 

For a key that consists of multiple segments, you must define the 
following elements for each key segment: 

+ Key Position 

+ Key Length 

+ Duplicate Key Values 

e Modifiable Key Values 

+ Key Type 


The Descending Sort Order element is optional for each 
segment. 


If any key in the file uses an ACS, you must specify an ACS file 
name, a country ID and code page ID, or an ISR table name. You 
can include this information as either the last element of the key 
(applies to current key only) or the last element in the 
description file (applies to entire data file). 


e Youcan specify only one ACS per key, and you must provide 
an ACS file name, country ID and code page ID, or an ISR 
table name. Different keys in the same file can use different 
types of ACSs; for example, Key 0 can use an ACS file name, 
and Key 1 can use a country ID and code page ID. 


Rules for Description Files 


+ Different segments of the same key cannot have different 
ACSs. 


+ Ifyou specify an ACS at the end of a description file, it is 
used as the default ACS. That is, if you specify 
alternate=y for a given key but do not include an ACS 
file name, country ID and code page ID, or an ISR table 
name for that key, the MicroKernel uses the ACS file name, 
country ID and code page ID, or ISR table name specified at 
the end of the file. 


+ Ifyou are creating a new key and you specify 
alternate=y but you omit the ACS file name, country 
ID and code page ID, or ISR table name, the MicroKernel 
does not create the key. 


If a Description File element is optional, you can omit it. 


Make sure the description file contains no text formatting 
characters. Some word processors embed formatting characters 
in a text file. 
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Description File Examples 


The sample description files shown in this section describe a data 
file. This data file has a page size of 512 bytes and 2 keys. The fixed- 
length portion of the record is 98 bytes long. The file allows variable- 
length records but does not use blank truncation. 


The file uses data compression, allows for Variable-tail Allocation 
Tables (VATs), and has the free space threshold set to 20 percent. The 
MicroKernel Database Engine preallocates 100 pages, or 51,200 
bytes, when it creates the file. The file has two keys: Key 0 and Key 1. 
Key 0 is a segmented key with two segments. 


In Figure A-1 on page A-4, both keys use the same ACS file name 
(UPPER.ALT). In Figure A-2 on page A-5, both keys use the same 
country ID (-1) and code page ID (-1). In Figure A-3 on page A-5, 
Key 0 and Key 1 use different ACS file names (LOWER.ALT and 
UPPER.ALT, respectively). In Figure A-4 on page A-5, the file has no 
keys except the system-defined key used for logging. 


Figure A-1 Sample Description File Using Alternate Collating Sequence File 
Name 





record=98 variable=y truncate=n compress=y 


key=2 page=512 allocation=100 replace=n File 
fthreshold=20 vats=y _] Specifications 
position=1 length=5 duplicates=y Key 0 
modifiable=n type=string alternate=y ic 
nullkey=allsegs value=20 segment=y 4 g 
position=6 length=10 duplicates=y lke 0 
modifiable=n type=string alternate=y Segment 2 


nullkey=allsegs value=20 segment=n 


position=16 length=2 duplicates=n 
modifiable=y type=numeric descending=y Key 1 
alternate=y nullkey=n segment=n 





name=sys : \pvsw\demodata\upper.alt 
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Figure A-2 Sample Description File Using Alternate Collating Sequence ID 








record=98 variable=y truncate=n compress=y 
key=2 page=512 allocation=100 replace=n 
fthreshold=20 vats=y 


position=1 length=5 duplicates=y 
modifiable=n type=string alternate=y 
nullkey=allsegs value=20 segment=y 


position=6 length=10 duplicates=y 
modifiable=n type=string alternate=y 
nullkey=allsegs value=20 segment=n 





position=16 length=2 duplicates=n 
modifiable=y type=numeric descending=y 
alternate=y nullkey=n segment=n 


countryid=-1 codepageid=-1 





File 
_| Specifications 


Key 0 
Segment 1 


Key 0 
Segment 2 


Key 1 








Figure A-3 Sample Description File Using Alternate Collating Sequence File 


Name 
on a Key Segment 








record=98 variable=y truncate=n compress=y 
key=2 page=512 allocation=100 replace=n 
fthreshold=20 vats=y 


position=1 length=5 duplicates=y 
modifiable=n type=string alternate=y 
nullkey=allsegs value=20 segment=y 

name=sys: \pvsw\demodata\lower.alt 


position=6 length=10 duplicates=y 
modifiable=n type=string alternate=y 
nullkey=allsegs value=20 segment=n 

name=sys: \pvsw\demodata\lower.alt 








position=16 length=2 duplicates=n 
modifiable=y type=numeric descending=y 
alternate=y nullkey=n segment=n 
name=sys: \pvsw\demodata\upper.alt 





File 
_| Specifications 


Key 0 
Segment 1 


Key 0 
Segment 2 


Key 1 








Figure A-4 Sample Description File Using System-Defined Key for Logging 
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record=98 variable=y truncate=n compress=y 
key=2 page=512 allocation=100 replace=n 
fthreshold=20 vats=y sysdataonrecord=loggable 
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Description File Elements 


Description file elements must appear in a particular order. Table 

A-1 on page A-7 lists the description file elements in the appropriate 
order. For each element, the table specifies the required format and 
the range of acceptable values. 


= An asterisk (*) indicates that the element is optional. 


=» A pound sign (+) indicates that it is not applicable in the current 
MicroKernel version but is retained for backward compatibility 
with previous MicroKernel versions. 


= A percent sign (%) indicates that the element is applicable only 
to the current MicroKernel version. 
































Table A-1 Summary of Description File Elements 

Element Keyword and Format Range Comments 

File 

Specification 

Information 

Comment Block* | /*............ */ 5,120 None. 

bytes 

Record Length record=nnnn 4-4,088 None. 

Variable-Length | variable=<y|n> N/A Not applicable to key- 

Records only files. 

Reserved dupkey=<nnn> 0-119 Applicable only to 

Duplicate files for which you 

Pointer* plan to add linked- 
duplicatable keys. 

Blank truncate=<yln> N/A Not applicable for 

Truncation* files that use data 
compression. 

Data compress=<yl|n> N/A Not applicable to key- 

Compression” only files. 

Key Count key=nnn 0-119 Specify 0 to create a 
data-only file. 

Page Size page=nnnn 512-4,096 | Must be a multiple of 











512. 











A-7 


Description Files 


A-8 
































Table A-1 Summary of Description File Elements continued 

Element Keyword and Format Range Comments 

Page allocation=nnnnn 1-65,535 | None. 

Preallocation* 

Replace Existing | replace=<yln> N/A None. 

File*# 

Include Data* data=<y|n> N/A Specify nto create a 
key-only file. Cannot 
create a key-only file 
that both allows 
duplicates and uses a 
system-defined key. 

Free Space fthreshold=<5110120130> | N/A Applicable only for 

Threshold* files that have 
variable-length 
records. The default 
is 5. 

Variable-Tail huge=<yln> # N/A Applicable only for 

Allocation Tables | vats=<yln> files that have 

(VATs) variable-length 
records. 

Balanced Index* | balance=<yln> N/A None. 

Use Key Number | usekeynum=<yln> N/A Used with the Key 

il Number element. 

TUse System sysdataonrecord= N/A If no element 

Data*% <nlloggable> specified, 
MicroKernel 











configuration is used. 
If creating a key-only 
file, MicroKernel 
configuration is used 
and this element is 
ignored. Also, you 
cannot create a key- 
only file that both 
allows duplicates and 
uses a system- 
defined key. 
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Table A-1 Summary of Description File Elements continued 
Element Keyword and Format Range Comments 
Key 
Specification 
Information 
Key Number * keynum=nnnn 0-118 Must be unique to the 
file, specified in 
ascending order, and 
valid for the file’s 
Page Size. Applicable 
only when creating a 
file. 
Key Position position=nnnn 1-4,088 Cannot exceed the 
Record Length. 
Key Length length=nnn key type Cannot exceed the 
limit limit dictated by the 
Key Type. For binary 
keys, the key length 
must be an even 
number. The total of 
the Key Position and 
Key Length cannot 
exceed the file’s 
Record Length. 
Duplicate Key duplicates=<y|n> N/A Cannot create a key- 
Values only file that allows 
duplicates and uses a 
system-defined key. 
Modifiable Key modifiable=<y|n> N/A None. 
Values 
Key Type type= N/A Can enter the entire 
validMKDEKey Type word (as in float) or 
just the first three 
letters (as in flo). 
Descending Sort | descending=<y|n> N/A None. 


Order* 
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Table A-1 Summary of Description File Elements continued 

Element Keyword and Format Range Comments 

Alternate alternate=<yln> N/A Applicable only for 

Collating case sensitive 

Sequence STRING, LSTRING, 
or ZSTRING keys. 
When creating an 
additional index for 
an existing file, if you 
want the index to use 
an ACS other than 
the first one in the 
data file, use with 
caseinsensitiv 
e=y. 

Case-Insensitive | caseinsensitive=<y|n> N/A Applicable only for 

Key* STRING, LSTRING, 
or ZSTRING keys 
that do not use an 
ACS. 

Repeating repeatdup=<yln> N/A If creating a key-only 

Duplicates* file, use repeating 
duplicates. If using 
this element, you 
must use 
duplicates=y. 

Null Segments* | nullkey=<allsegs | n | N/A None. 

anyseg l> 

Null Key Value value=nn 1-byte hex | Used with the Null 
Segments element. 

Segmented Key | segment=<y|n> N/A None. 

Alternate name=sequenceFile or valid path Used with the 

Collating countryid=nnn and or values Alternate Collating 

Sequence File codepageid=nnn valid to Sequence element. 

Name/ID isr=table name (%) operating 

system or 








-1 








1 When the MicroKernel adds a system key, the resulting records may be too 
large to fit in the file’s existing page size. In such cases, the MicroKernel auto- 
matically increases the file’s page size to the next accommodating size. 
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ODBC Connection Mgr Supported Protocol 4-8 
ODBC tracing 
performance and 3-19 
OEM to ANSI 
character translation 5-8 
connection string 5-8 
Open modes 5-5 
OPENMODE connection string 5-10 
Operation Bundle Limit 4-12 
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delete rule 6-2 
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Repeating-duplicatable keys 
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MicroKernel 10-13 
Restore and backup 8-1 
Restoring data files 8-1 
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BUTILand 8-8 
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SET SECURITY 
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Btrieve Maintenance utility and 13-20 
BUTIL and 13-54 
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ordered by default view 3-8 
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SPX connection timeout 4-34 
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overview of 2-5 
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ENDBU command 8-20 
overview 8-18 
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STOP command 13-63 
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